How to Organize Selenium Project for Clean and Scalable Tests

To organize a Selenium project, create a clear folder structure separating tests, page objects, and utilities. Use the Page Object Model to keep locators and actions in one place, and group tests logically for easy maintenance.

Syntax

A typical Selenium project structure includes folders for page objects (classes representing web pages), tests (test scripts), and utilities (helpers like drivers or config). Each test imports page objects to interact with the UI.

Example folder structure:

• pages/ - page object classes
• tests/ - test scripts
• utils/ - helper functions and setup
• drivers/ - browser drivers

plaintext

project_root/
  pages/
    LoginPage.py
    HomePage.py
  tests/
    test_login.py
    test_home.py
  utils/
    driver_setup.py
  drivers/
    chromedriver.exe

Example

This example shows a simple Selenium project using the Page Object Model. The LoginPage class holds locators and actions for the login page. The test script uses this class to perform a login test.

python

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

# pages/LoginPage.py
class LoginPage:
    def __init__(self, driver):
        self.driver = driver
        self.username_input = (By.ID, 'username')
        self.password_input = (By.ID, 'password')
        self.login_button = (By.ID, 'loginBtn')

    def enter_username(self, username):
        self.driver.find_element(*self.username_input).send_keys(username)

    def enter_password(self, password):
        self.driver.find_element(*self.password_input).send_keys(password)

    def click_login(self):
        self.driver.find_element(*self.login_button).click()

# tests/test_login.py
import unittest
from pages.LoginPage import LoginPage

class TestLogin(unittest.TestCase):
    def setUp(self):
        self.driver = webdriver.Chrome()
        self.driver.get('https://example.com/login')
        self.login_page = LoginPage(self.driver)

    def test_valid_login(self):
        self.login_page.enter_username('user1')
        self.login_page.enter_password('pass123')
        self.login_page.click_login()
        self.assertIn('Dashboard', self.driver.title)

    def tearDown(self):
        self.driver.quit()

if __name__ == '__main__':
    unittest.main()

Output

Ran 1 test in X.XXXs

OK

Common Pitfalls

Common mistakes when organizing Selenium projects include:

• Mixing test logic and page locators in the same file, making maintenance hard.
• Not using a clear folder structure, causing confusion as the project grows.
• Hardcoding locators inside tests instead of using page objects.
• Not separating setup and teardown code, leading to duplicated code.

Always keep page objects separate and reuse them in tests for clarity and scalability.

python

## Wrong way: locator inside test

# tests/test_login.py
from selenium.webdriver.common.by import By

username_input = (By.ID, 'username')

# test code directly uses locator
self.driver.find_element(*username_input).send_keys('user1')

## Right way: use page object

class LoginPage:
    def __init__(self, driver):
        self.driver = driver
        self.username_input = (By.ID, 'username')

    def enter_username(self, username):
        self.driver.find_element(*self.username_input).send_keys(username)

Quick Reference

• Use Page Object Model: Keep locators and actions in page classes.
• Separate folders: pages/, tests/, utils/, drivers/.
• Setup/Teardown: Use test framework hooks to initialize and close browsers.
• Group tests: Organize tests by feature or functionality.
• Use config files: Store URLs, credentials, and settings outside code.

Key Takeaways

Organize Selenium projects with clear folders for pages, tests, and utilities.

Use the Page Object Model to separate locators and actions from test logic.

Keep setup and teardown code centralized to avoid duplication.

Group tests logically for easier maintenance and scalability.

Store configuration data outside test code for flexibility.