The Token Social Bit, the Page Pattern, and an Exercise for the Reader

The Token Social Bit, the Page Pattern, and an Exercise for the Reader

Warning, Chapter Update in Progress

🚧 Warning, this chapter has only recently been updated to Django 5. The listings should all be copacetic, I haven’t had time to review the text in detail.

Still, it’s a fun chapter, give it a go, and let me know how you enjoy it!

Are jokes about how "everything has to be social now" slightly old hat? Yes Harry, they were old hat 10 years ago when you started writing this book, and they’re positively prehistoric now. Irregardless, let’s say lists are often better shared. We should allow our users to collaborate on their lists with other users.

Along the way we’ll improve our FTs by starting to implement something called the Page object pattern.

Then, rather than showing you explicitly what to do, I’m going to let you write your unit tests and application code by yourself. Don’t worry, you won’t be totally on your own! I’ll give an outline of the steps to take, as well as some hints and tips.

An FT with Multiple Users, and addCleanup

Let’s get started—we’ll need two users for this FT:

src/functional_tests/test_sharing.py (ch24l001)

from selenium import webdriver
from selenium.webdriver.common.by import By

from .base import FunctionalTest


def quit_if_possible(browser):
    try:
        browser.quit()
    except:
        pass


class SharingTest(FunctionalTest):
    def test_can_share_a_list_with_another_user(self):
        # Edith is a logged-in user
        self.create_pre_authenticated_session("[email protected]")
        edith_browser = self.browser
        self.addCleanup(lambda: quit_if_possible(edith_browser))

        # Her friend Onesiphorus is also hanging out on the lists site
        oni_browser = webdriver.Firefox()
        self.addCleanup(lambda: quit_if_possible(oni_browser))
        self.browser = oni_browser
        self.create_pre_authenticated_session("[email protected]")

        # Edith goes to the home page and starts a list
        self.browser = edith_browser
        self.browser.get(self.live_server_url)
        self.add_list_item("Get help")

        # She notices a "Share this list" option
        share_box = self.browser.find_element(By.CSS_SELECTOR, 'input[name="sharee"]')
        self.assertEqual(
            share_box.get_attribute("placeholder"),
            "[email protected]",
        )

The interesting feature to note about this section is the addCleanup function, whose documentation you can find online. It can be used as an alternative to the tearDown function as a way of cleaning up resources used during the test. It’s most useful when the resource is only allocated halfway through a test, so you don’t have to spend time in tearDown figuring out what does or doesn’t need cleaning up.

addCleanup is run after tearDown, which is why we need that try/except formulation for quit_if_possible; whichever of edith_browser and oni_browser is also assigned to self.browser at the point at which the test ends will already have been quit by the tearDown function.

We’ll also need to move create_pre_authenticated_session from test_my_lists.py into base.py.

OK, let’s see if that all works:

$ python src/manage.py test functional_tests.test_sharing
[...]
Traceback (most recent call last):
  File "...goat-book/src/functional_tests/test_sharing.py", line 33, in
test_can_share_a_list_with_another_user
[...]
selenium.common.exceptions.NoSuchElementException: Message: Unable to locate
element: input[name="sharee"]; [...]

Great! It seems to have got through creating the two user sessions, and it gets onto an expected failure—there is no input for an email address of a person to share a list with on the page.

Let’s do a commit at this point, because we’ve got at least a placeholder for our FT, we’ve got a useful modification of the create_pre_authenticated_session function, and we’re about to embark on a bit of an FT refactor:

$ git add src/functional_tests
$ git commit -m "New FT for sharing, move session creation stuff to base"

The Page Pattern

Before we go any further, I want to show an alternative method for reducing duplication in your FTs, called "Page objects".

We’ve already built several helper methods for our FTs, including add_list_item which we’ve used here, but if we just keep adding more and more, it’s going to get very crowded. I’ve worked on a base FT class that was over 1,500 lines long, and that got pretty unwieldy.

Page objects are an alternative which encourage us to store all the information and helper methods about the different types of pages on our site in a single place. Let’s see how that might look for our site, starting with a class to represent any lists page:

src/functional_tests/list_page.py

from selenium.webdriver.common.by import By
from selenium.webdriver.common.keys import Keys

from .base import wait


class ListPage:
    def __init__(self, test):
        self.test = test  (1)

    def get_table_rows(self):  (3)
        return self.test.browser.find_elements(By.CSS_SELECTOR, "#id_list_table tr")

    @wait
    def wait_for_row_in_list_table(self, item_text, item_number):  (2)
        expected_row_text = f"{item_number}: {item_text}"
        rows = self.get_table_rows()
        self.test.assertIn(expected_row_text, [row.text for row in rows])

    def get_item_input_box(self):  (2)
        return self.test.browser.find_element(By.ID, "id_text")

    def add_list_item(self, item_text):  (2)
        new_item_no = len(self.get_table_rows()) + 1
        self.get_item_input_box().send_keys(item_text)
        self.get_item_input_box().send_keys(Keys.ENTER)
        self.wait_for_row_in_list_table(item_text, new_item_no)
        return self  (4)

1	It’s initialised with an object that represents the current test. That gives us the ability to make assertions, access the browser instance via `self.test.browser`, and use the `self.test.wait_for` function.
2	I’ve copied across some of the existing helper methods from base.py, but I’ve tweaked them slightly…
3	For example, this new method is used in the new versions of the old helper methods.
4	Returning `self` is just a convenience. It enables method chaining, which we’ll see in action immediately.

Let’s see how to use it in our test:

src/functional_tests/test_sharing.py (ch24l004)

from .list_page import ListPage
[...]

        # Edith goes to the home page and starts a list
        self.browser = edith_browser
        self.browser.get(self.live_server_url)
        list_page = ListPage(self).add_list_item("Get help")

Let’s continue rewriting our test, using the Page object whenever we want to access elements from the lists page:

src/functional_tests/test_sharing.py (ch24l008)

        # She notices a "Share this list" option
        share_box = list_page.get_share_box()
        self.assertEqual(
            share_box.get_attribute("placeholder"),
            "[email protected]",
        )

        # She shares her list.
        # The page updates to say that it's shared with Onesiphorus:
        list_page.share_list_with("[email protected]")

We add the following three functions to our ListPage:

src/functional_tests/list_page.py (ch24l009)

    def get_share_box(self):
        return self.test.browser.find_element(
            By.CSS_SELECTOR,
            'input[name="sharee"]',
        )

    def get_shared_with_list(self):
        return self.test.browser.find_elements(
            By.CSS_SELECTOR,
            ".list-sharee",
        )

    def share_list_with(self, email):
        self.get_share_box().send_keys(email)
        self.get_share_box().send_keys(Keys.ENTER)
        self.test.wait_for(
            lambda: self.test.assertIn(
                email, [item.text for item in self.get_shared_with_list()]
            )
        )

The idea behind the Page pattern is that it should capture all the information about a particular page in your site, so that if, later, you want to go and make changes to that page—even just simple tweaks to its HTML layout, for example—you have a single place to go to adjust your functional tests, rather than having to dig through dozens of FTs.

The next step would be to pursue the FT refactor through our other tests. I’m not going to show that here, but it’s something you could do, for practice, to get a feel for what the trade-offs between DRY and test readability are like…

Extend the FT to a Second User, and the "My Lists" Page

Let’s spec out just a little more detail of what we want our sharing user story to be. Edith has seen on her list page that the list is now "shared with" Onesiphorus, and then we can have Oni log in and see the list on his "My Lists" page, maybe in a section called "lists shared with me":

src/functional_tests/test_sharing.py (ch24l010)

from .my_lists_page import MyListsPage
[...]

        list_page.share_list_with("[email protected]")

        # Onesiphorus now goes to the lists page with his browser
        self.browser = oni_browser
        MyListsPage(self).go_to_my_lists_page()

        # He sees Edith's list in there!
        self.browser.find_element(By.LINK_TEXT, "Get help").click()

That means another function in our MyListsPage class:

src/functional_tests/my_lists_page.py (ch24l011)

from selenium.webdriver.common.by import By


class MyListsPage:
    def __init__(self, test):
        self.test = test

    def go_to_my_lists_page(self):
        self.test.browser.get(self.test.live_server_url)
        self.test.browser.find_element(By.LINK_TEXT, "My lists").click()
        self.test.wait_for(
            lambda: self.test.assertEqual(
                self.test.browser.find_element(By.TAG_NAME, "h1").text,
                "My Lists",
            )
        )
        return self

Once again, this is a function that would be good to carry across into test_my_lists.py, along with maybe a MyListsPage object.

In the meantime, Onesiphorus can also add things to the list:

src/functional_tests/test_sharing.py (ch24l012)

    # On the list page, Onesiphorus can see says that it's Edith's list
    self.wait_for(
        lambda: self.assertEqual(list_page.get_list_owner(), "[email protected]")
    )

    # He adds an item to the list
    list_page.add_list_item("Hi Edith!")

    # When Edith refreshes the page, she sees Onesiphorus's addition
    self.browser = edith_browser
    self.browser.refresh()
    list_page.wait_for_row_in_list_table("Hi Edith!", 2)

That’s another addition to our ListPage object:

src/functional_tests/list_page.py (ch24l013)

class ListPage:
    [...]

    def get_list_owner(self):
        return self.test.browser.find_element(By.ID, "id_list_owner").text

It’s long past time to run the FT and check if all of this works!

$ python src/manage.py test functional_tests.test_sharing

    share_box = list_page.get_share_box()
    [...]
selenium.common.exceptions.NoSuchElementException: Message: Unable to locate
element: input[name="sharee"]; [...]

That’s the expected failure; we don’t have an input for email addresses of people to share with. Let’s do a commit:

$ git add src/functional_tests
$ git commit -m "Create Page objects for list pages, use in sharing FT"

An Exercise for the Reader

I probably didn’t really understand what I was doing until after having completed the "Exercise for the reader" in The Token Social Bit, the Page Pattern, and an Exercise for the Reader.

— Iain H. (reader)

There’s nothing that cements learning like taking the training wheels off, and getting something working on your own, so I hope you’ll give this a go.

Here’s an outline of the steps you could take:

We’ll need a new section in list.html, with, at first, a form with an input box for an email address. That should get the FT one step further.
Next, we’ll need a view for the form to submit to. Start by defining the URL in the template, maybe something like lists/<list_id>/share.
Then, our first unit test. It can be just enough to get a placeholder view in. We want the view to respond to POST requests, and it should respond with a redirect back to the list page, so the test could be called something like ShareListTest.test_post_redirects_to_lists_page.
We build out our placeholder view, as just a two-liner that finds a list and redirects to it.
We can then write a new unit test which creates a user and a list, does a POST with their email address, and checks that the user is added to mylist.shared_with.all() (a similar ORM usage to "My Lists"). That shared_with attribute won’t exist yet; we’re going outside-in.
So before we can get this test to pass, we have to move down to the model layer. The next test, in test_models.py, can check that a list has a shared_with.add method, which can be called with a user’s email address and then check the lists' shared_with.all() queryset, which will subsequently contain that user.
You’ll then need a ManyToManyField. You’ll probably see an error message about a clashing related_name, which you’ll find a solution to if you look around the Django docs.
It will need a database migration.
That should get the model tests passing. Pop back up to fix the view test.
You may find the redirect view test fails, because it’s not sending a valid POST request. You can either choose to ignore invalid inputs, or adjust the test to send a valid POST.
Then back up to the template level; on the "My Lists" page we’ll want a <ul> with a for loop of the lists shared with the user. On the lists page, we also want to show who the list is shared with, as well as mention of who the list owner is. Look back at the FT for the correct classes and IDs to use. You could have brief unit tests for each of these if you like, as well.
You might find that spinning up the site with runserver will help you iron out any bugs, as well as fine-tune the layout and aesthetics. If you use a private browser session, you’ll be able to log multiple users in.

By the end, you might end up with something that looks like Sharing lists.

The Page Pattern, and the Real Exercise for the Reader

Apply DRY to your functional tests: Once your FT suite starts to grow, you’ll find that different tests will inevitably find themselves using similar parts of the UI. Try to avoid having constants, like the HTML IDs or classes of particular UI elements, duplicated between your FTs.
The Page pattern: Moving helper methods into a base FunctionalTest class can become unwieldy. Consider using individual Page objects to hold all the logic for dealing with particular parts of your site.
An exercise for the reader: I hope you’ve actually tried this out! Try to follow the outside-in method, and occasionally try things out manually if you get stuck. The real exercise for the reader, of course, is to apply TDD to your next project. I hope you’ll enjoy it!

In the next chapter, we’ll wrap up with a discussion of testing "best practices."