Project structure for tests in PyTest - Deep Dive

Overview - Project structure for tests

What is it?

Project structure for tests means organizing your test files and folders in a clear, consistent way inside your software project. It helps you find, run, and maintain tests easily. In pytest, this usually involves placing test files in specific directories and naming them so pytest can discover them automatically. Good structure makes testing faster and less confusing for everyone.

Why it matters

Without a clear project structure, tests get lost or mixed up, making it hard to know what is tested or to add new tests. This slows down fixing bugs and building new features. A good structure saves time, reduces mistakes, and helps teams work together smoothly. It also makes automated testing tools like pytest work correctly and efficiently.

Where it fits

Before learning project structure, you should know basic pytest test writing and running tests. After mastering structure, you can learn advanced pytest features like fixtures, parametrization, and continuous integration setups. Structure is a foundation for scaling tests in bigger projects.

Mental Model

Core Idea

Organizing test files and folders clearly lets pytest find and run tests automatically, making testing easy and reliable.

Think of it like...

Think of your test project like a well-organized kitchen: ingredients (test files) are stored in labeled cabinets (folders), so you can quickly find what you need to cook (run tests) without searching everywhere.

ProjectRoot/
├── src/               # Your application code
│   └── ...
├── tests/             # All test files here
│   ├── test_module1.py
│   ├── test_module2.py
│   └── helpers/       # Test helper files
│       └── conftest.py
└── pytest.ini         # Optional pytest config file

Build-Up - 7 Steps

1

Foundation

Basic test file placement

Concept: Tests should be placed in a dedicated folder named 'tests' at the project root.

Create a folder named 'tests' next to your main code folder. Put all your test files inside this folder. Name test files starting with 'test_' so pytest can find them automatically. For example, 'test_example.py'.

Result

Pytest automatically discovers and runs all tests inside the 'tests' folder without extra configuration.

Understanding that pytest looks for test files in specific places and with specific names helps you organize tests so they run without manual setup.

2

Foundation

Naming conventions for test files

Concept: Test files and test functions must follow naming rules for pytest discovery.

Test files should start with 'test_' or end with '_test.py'. Inside these files, test functions should start with 'test_'. For example, 'test_addition.py' with function 'def test_sum()'. This naming lets pytest find and run tests automatically.

Result

Tests are discovered and executed by pytest without needing to specify file or function names.

Knowing naming conventions prevents tests from being skipped accidentally and keeps test runs complete.

3

Intermediate

Organizing tests by feature or module

🤔Before reading on: do you think grouping tests by feature or by test type is better for maintenance? Commit to your answer.

Concept: Tests are grouped in subfolders or files that mirror the application structure or features.

Inside the 'tests' folder, create subfolders or separate test files that correspond to your app's modules or features. For example, tests/authentication/test_login.py for login tests. This makes it easier to find and run tests related to specific parts of your app.

Result

Test organization matches app structure, making tests easier to maintain and understand.

Organizing tests like your app code helps you quickly locate and update tests when features change.

4

Intermediate

Using conftest.py for shared fixtures

🤔Before reading on: do you think conftest.py should be placed inside each test folder or only once at the root? Commit to your answer.

Concept: conftest.py files hold shared setup code (fixtures) for tests in their folder and subfolders.

Place a conftest.py file inside the 'tests' folder or subfolders to define fixtures that multiple tests can use. For example, a database connection fixture used by many tests. Pytest automatically finds and applies these fixtures without imports.

Result

Tests share setup code cleanly, reducing duplication and improving maintainability.

Knowing how conftest.py scopes fixtures helps you share setup code efficiently across tests.

5

Advanced

Configuring pytest with pytest.ini

🤔Before reading on: do you think pytest.ini is required for test discovery or only for customizing behavior? Commit to your answer.

Concept: pytest.ini configures pytest behavior like test paths, markers, and options.

Create a pytest.ini file at the project root to customize pytest. For example, specify 'testpaths = tests' to tell pytest where to look for tests, or add markers for grouping tests. This file helps standardize test runs across environments.

Result

Pytest runs consistently with your project settings, avoiding surprises in test discovery or execution.

Understanding pytest.ini lets you control test discovery and behavior, making test runs predictable and configurable.

6

Advanced

Separating unit and integration tests

Concept: Organize different test types in separate folders or with markers for clarity and control.

Inside 'tests', create folders like 'unit' and 'integration' to separate fast, isolated tests from slower, environment-dependent ones. Use pytest markers (e.g., @pytest.mark.integration) to tag tests. This helps run only relevant tests during development or deployment.

Result

You can run quick unit tests frequently and run integration tests separately, improving feedback speed.

Separating test types improves efficiency and clarity in large projects with many tests.

7

Expert

Handling large test suites with modular structure

🤔Before reading on: do you think a flat test folder or deeply nested folders scale better for large projects? Commit to your answer.

Concept: Large projects benefit from modular test structures with clear boundaries and reusable components.

For big projects, organize tests into multiple layers: feature folders, shared helpers, and common fixtures in conftest.py files at different levels. Use pytest plugins and custom markers to manage test selection. This modular approach keeps tests maintainable and scalable.

Result

Test suites remain fast, organized, and easy to navigate even as they grow very large.

Knowing how to modularize tests prevents chaos and performance issues in big projects.

Under the Hood

Pytest uses a discovery process that scans folders and files matching naming patterns (like test_*.py) to find test functions. It builds a collection tree of tests, applying fixtures from conftest.py files based on folder hierarchy. The pytest.ini file configures discovery rules and test behavior. This layered approach lets pytest run tests efficiently and apply shared setup automatically.

Why designed this way?

Pytest was designed to require minimal configuration by using conventions like naming and folder structure, making it easy for beginners. At the same time, it supports complex setups via conftest.py and config files for advanced users. This balance allows pytest to scale from small scripts to large projects.

ProjectRoot
├─ src/
│   └─ app_code.py
├─ tests/
│   ├─ conftest.py  <-- fixtures here apply to all tests below
│   ├─ test_feature1.py
│   ├─ feature2/
│   │   ├─ conftest.py  <-- fixtures here override or add for feature2
│   │   └─ test_part.py
│   └─ pytest.ini    <-- config controls discovery and options

Pytest discovery flow:
[pytest.ini config] -> [tests folder scan] -> [file name match] -> [function name match] -> [apply fixtures from conftest.py] -> [run tests]

Myth Busters - 4 Common Misconceptions

Quick: Do you think pytest will find tests in any folder regardless of name? Commit to yes or no.

Common Belief: Pytest finds tests anywhere in the project, no matter the folder or file names.

Reality: Pytest only discovers tests in files and folders that match its naming conventions or are specified in config files.

Why it matters: If tests are placed in wrong folders or named incorrectly, pytest will skip them silently, causing missing test coverage.

Quick: Is it okay to put all tests in one big file for simplicity? Commit to yes or no.

Common Belief: Putting all tests in one file is simpler and just as good as organizing them in folders.

Reality: Large test files become hard to maintain and slow to navigate; organizing tests by feature or module improves clarity and speed.

Why it matters: Poor organization leads to confusion, duplicated tests, and slower development cycles.

Quick: Does conftest.py need to be imported in test files to work? Commit to yes or no.

Common Belief: You must import conftest.py in each test file to use its fixtures.

Reality: Pytest automatically finds and applies fixtures from conftest.py based on folder hierarchy without imports.

Why it matters: Trying to import conftest.py manually can cause import errors and confusion about fixture scope.

Quick: Can pytest.ini change where pytest looks for tests? Commit to yes or no.

Common Belief: pytest.ini only configures test running options, not test discovery paths.

Reality: pytest.ini can specify 'testpaths' to control which folders pytest searches for tests.

Why it matters: Without configuring testpaths, pytest might miss tests or run unwanted files, causing inconsistent test runs.

Expert Zone

1

Fixtures in conftest.py can be scoped at function, class, module, or session level, affecting performance and test isolation subtly.

2

pytest's test discovery can be customized with plugins and hooks, allowing complex project structures beyond default conventions.

3

Using markers and pytest.ini together enables selective test runs, which is crucial for large projects with mixed test types.

When NOT to use

For very small scripts or one-off tests, complex project structures add unnecessary overhead; simple flat test files suffice. Also, if using other test frameworks like unittest or nose, their conventions differ and pytest structure may not apply.

Production Patterns

In real projects, tests mirror the app's package structure, with conftest.py files providing shared fixtures per feature. Continuous integration pipelines run tests from configured folders using pytest.ini. Markers separate slow integration tests from fast unit tests, enabling efficient test runs.

Connections

Software Architecture

Project structure for tests mirrors software architecture patterns.

Understanding how app code is organized helps design test folders that align, making maintenance easier.

Version Control Systems

Test project structure affects how tests are tracked and merged in version control.

Clear test organization reduces merge conflicts and helps teams collaborate on tests effectively.

Library Classification Systems

Both organize items into categories and subcategories for easy retrieval.

Knowing how libraries classify books helps understand why tests are grouped by feature or type for quick access.

Common Pitfalls

#1 Tests not discovered because files are misnamed.

Wrong approach:

tests/
example.py
testexample.py
example_test.py

Correct approach:

tests/
test_example.py
test_another.py

Root cause:

Not following pytest naming conventions causes tests to be skipped silently.

#2 Importing conftest.py manually in test files.

Wrong approach:

from tests import conftest

def test_something():
fixture = conftest.some_fixture()

Correct approach:

def test_something(some_fixture):
assert some_fixture is not None

Root cause:

Misunderstanding pytest's automatic fixture discovery and injection.

#3 Mixing unit and integration tests in one folder without markers.

Wrong approach:

tests/
test_unit_feature.py
test_integration_feature.py

# No markers or separation

Correct approach:

tests/
unit/
test_feature.py
integration/
test_feature.py

# Or use @pytest.mark.integration on integration tests

Root cause:

Ignoring test type separation leads to slow test runs and unclear test purposes.

Key Takeaways

Organizing tests in a dedicated 'tests' folder with proper naming lets pytest find and run them automatically.

Mirroring your application structure in test folders improves maintainability and clarity.

conftest.py files provide a powerful way to share setup code across tests without manual imports.

pytest.ini configures test discovery and behavior, making test runs consistent across environments.

Separating test types and modularizing large test suites keeps testing efficient and scalable.