Docker Docs

Appearance

Fresh

Run tests ​

Back

Guides

Getting started with Testcontainers for Python

Learn how to create a Python application and test database interactions using Testcontainers for Python with a real PostgreSQL instance.

Python Testing with Docker

15 minutes

1

Create the project

2

Write tests

3

Run tests

« Back to all guides

Run tests and next steps ​

Copy as Markdown

Open MarkdownAsk Docs AIClaudeOpen in Claude

Table of contents

Run the tests ​

Run the tests using pytest:

console
$ pytest -v

You should see output similar to:

text
============================= test session starts ==============================
platform linux -- Python 3.13.x, pytest-9.x.x
collected 2 items

tests/test_customers.py::test_get_all_customers PASSED                   [ 50%]
tests/test_customers.py::test_get_customer_by_email PASSED               [100%]

============================== 2 passed in 1.90s ===============================

The tests run against a real PostgreSQL database instead of mocks, which gives more confidence in the implementation.

Summary ​

The Testcontainers for Python library helps you write integration tests using the same type of database (Postgres) that you use in production, instead of mocks. Because you aren't using mocks and instead talk to real services, you're free to refactor code and still verify that the application works as expected.

In addition to PostgreSQL, Testcontainers for Python provides modules for many SQL databases, NoSQL databases, messaging queues, and more. You can use Testcontainers to run any containerized dependency for your tests.

To learn more about Testcontainers, visit the Testcontainers overview.

Further reading ​