Introduction
As Selenium projects grow, maintaining automation scripts becomes challenging if everything is written inside a single file. Modern automation frameworks solve this problem by organizing code into separate folders and reusable components.
A well-designed framework folder structure improves:
Code readability
Reusability
Maintainability
Scalability
Team collaboration
CI/CD integration
Test execution and reporting
Most real-world Selenium projects follow a structured approach by separating test cases, page objects, utilities, configurations, reports, screenshots, and test data into dedicated folders.
In this tutorial, you will learn what a framework folder structure is, why it is important, how Selenium projects are organized, real-world examples, best practices, and frequently asked interview questions.
What is a Framework Folder Structure?
A framework folder structure is the organized arrangement of files and folders within an automation project.
Instead of keeping everything in one file:
project.py
- Login Tests
- Utilities
- Reports
- Screenshots
- Configurations
- Test Data
- Page Objects
we organize them into separate folders.
Automation Framework
│
├── tests/
├── pages/
├── utilities/
├── config/
├── test_data/
├── reports/
├── screenshots/
└── requirements.txt
This makes large automation projects easier to maintain.
Why Do We Need a Proper Folder Structure?
A proper framework structure helps to:
Write reusable code.
Reduce duplication.
Organize automation projects efficiently.
Improve collaboration among team members.
Simplify maintenance.
Integrate easily with CI/CD pipelines.
Improve reporting and debugging.
Recommended Selenium Framework Structure
A commonly used Selenium framework structure is:
selenium_framework/
│
├── tests/
│
├── pages/
│
├── utilities/
│
├── config/
│
├── test_data/
│
├── reports/
│
├── screenshots/
│
├── logs/
│
├── requirements.txt
│
├── pytest.ini
│
└── conftest.py
Each folder has a specific responsibility within the framework.
Understanding Each Folder
tests/
Contains all automation test cases.
tests/
│
├── test_login.py
├── test_checkout.py
└── test_profile.py
Responsibilities:
Execute test scenarios.
Perform assertions.
Verify application behavior.
pages/
Contains all Page Object Model (POM) classes.
pages/
│
├── login_page.py
├── dashboard_page.py
└── checkout_page.py
Responsibilities:
Store web element locators.
Perform page-specific actions.
Improve code reusability.
utilities/
Contains reusable helper methods.
utilities/
│
├── waits.py
├── logger.py
├── screenshots.py
└── browser_utils.py
Responsibilities:
Explicit waits.
Screenshot utilities.
Browser utilities.
Logging utilities.
config/
Stores framework configurations.
config/
│
└── config.py
Responsibilities:
Application URLs.
Browser configurations.
Environment settings.
Timeout values.
test_data/
Stores automation test data.
test_data/
│
├── users.json
├── login_data.csv
└── test_data.xlsx
Responsibilities:
Data-driven testing.
Multiple test datasets.
Environment-specific test data.
reports/
Stores generated automation reports.
reports/
│
├── allure-results/
├── allure-report/
└── html_reports/
Responsibilities:
Allure Reports.
PyTest HTML Reports.
Test execution summaries.
screenshots/
Stores screenshots captured during execution.
screenshots/
│
├── failed_tests/
└── passed_tests/
Responsibilities:
Failure screenshots.
Debugging test failures.
Visual validations.
logs/
Stores automation logs.
logs/
│
└── execution.log
Responsibilities:
Execution logs.
Failure details.
Framework debugging.
Important Framework Files
requirements.txt
Stores all project dependencies.
Example:
selenium
pytest
allure-pytest
webdriver-manager
openpyxl
Install all dependencies using:
pip install -r requirements.txt
pytest.ini
Stores PyTest configurations.
Example:
[pytest]
addopts = -v
testpaths = tests
Responsibilities:
PyTest settings.
Report configurations.
Test execution configurations.
conftest.py
Contains reusable PyTest fixtures.
Example:
import pytest
from selenium import webdriver
@pytest.fixture()
def driver():
driver = webdriver.Chrome()
yield driver
driver.quit()
Responsibilities:
Browser setup.
Browser teardown.
Shared fixtures.
Reusable configurations.
Complete Framework Structure
selenium_framework/
│
├── tests/
│ test_login.py
│ test_checkout.py
│
├── pages/
│ login_page.py
│ dashboard_page.py
│
├── utilities/
│ waits.py
│ logger.py
│ screenshots.py
│
├── config/
│ config.py
│
├── test_data/
│ users.json
│ login_data.xlsx
│
├── reports/
│ html_reports/
│ allure-results/
│
├── screenshots/
│ failed_tests/
│
├── logs/
│ execution.log
│
├── requirements.txt
│
├── pytest.ini
│
└── conftest.py
Automation Testing Example
Suppose you are automating an e-commerce application.
tests/
│
▼
test_login.py
│
▼
calls
│
▼
pages/login_page.py
│
▼
calls
│
▼
utilities/waits.py
│
▼
uses
│
▼
config/config.py
│
▼
captures
│
▼
reports/screenshots
This approach keeps the framework highly maintainable.
Real-World Example
Most product-based companies organize their Selenium frameworks using:
Page Object Model (POM)
PyTest Fixtures
Data-Driven Testing
Logging utilities
Reporting utilities
CI/CD integrations
Parallel execution support
Large frameworks may additionally include:
drivers/
database/
api/
docker/
jenkins/
github_actions/
depending on project requirements.
Common Mistakes Beginners Make
Keeping Everything in One File
Incorrect
project.py
5000 lines of code
This makes maintenance extremely difficult.
Better
tests/
pages/
utilities/
reports/
Always organize automation projects properly.
Mixing Test Data with Test Scripts
Incorrect
username = "admin123"
password = "password123"
inside every test file.
Better
test_data/
users.json
login.xlsx
Keep test data separate from test scripts.
Duplicating Utility Methods
Instead of writing:
time.sleep(5)
inside multiple files, create reusable utility methods.
Best Practices
Follow the Page Object Model design pattern.
Keep test cases and page classes separate.
Store test data independently.
Use reusable utility methods.
Maintain separate folders for reports and screenshots.
Use PyTest fixtures for setup and teardown operations.
Keep framework configurations centralized.
Conclusion
A proper framework folder structure is the foundation of every scalable Selenium automation project. Organizing tests, page objects, utilities, configurations, reports, and test data into separate folders makes automation frameworks easier to develop, maintain, and extend.
Real-world Selenium projects heavily rely on structured frameworks because they improve collaboration, support CI/CD pipelines, and simplify long-term maintenance.
Mastering framework organization is an important step toward building enterprise-level Selenium automation solutions.
Frequently Asked Questions (FAQs)
What is a framework folder structure?
It is the organized arrangement of files and folders within an automation framework.
Why is it important?
It improves maintainability, scalability, and code reusability.
What does the tests folder contain?
It contains automation test cases.
What is stored inside the pages folder?
It contains Page Object Model classes that store locators and page actions.
Why do we use conftest.py?
It stores reusable PyTest fixtures and common setup and teardown methods.
Key Takeaways
Framework folder structure improves code organization and maintainability.
Separate folders should be created for tests, page objects, utilities, configurations, reports, screenshots, and test data.
Page Object Model (POM) is commonly used in Selenium frameworks.
requirements.txt,pytest.ini, andconftest.pyare important framework files.Proper folder structures simplify debugging, reporting, and CI/CD integration.
Real-world Selenium projects rely heavily on reusable and scalable framework designs.
Understanding framework organization is an important Selenium automation and interview topic.