56.12 Testcontainers: integration tests against a real Postgres

Example 1: Docker is up

Type this:

docker info --format '{{.ServerVersion}}'

You will see:

27.3.1

What it means: The daemon is reachable.

Example 2: Install for Python

Type this:

pip install 'testcontainers[postgres]' psycopg[binary] pytest

You will see:

Successfully installed testcontainers-4.8.2 ...

What it means: Library plus a Postgres driver.

Example 3: Check

Type this:

python -c 'import testcontainers; print("ok")'

You will see:

ok

What it means: Ready.

Example 4: test_first.py

Type this:

from testcontainers.postgres import PostgresContainer
import psycopg

def test_select_one():
    with PostgresContainer('postgres:16-alpine', driver=None) as pg:
        with psycopg.connect(pg.get_connection_url()) as c:
            assert c.execute('select 1').fetchone()[0] == 1

You will see:

(file)

What it means: The container lives only inside the with block.

Example 5: Run

Type this:

pytest -q test_first.py

You will see:

1 passed in 4.21s

What it means: A real Postgres, in about four seconds.

Example 6: Nothing left

Type this:

docker ps -a --filter ancestor=postgres:16-alpine -q | wc -l

You will see:

0

What it means: Removed after the test.

Example 7: Watch

Type this:

docker ps --format '{{.Image}} {{.Ports}}'

You will see:

postgres:16-alpine 0.0.0.0:55012-5432/tcp
testcontainers/ryuk:0.11.0 0.0.0.0:55011-8080/tcp

What it means: Random port 55012 for Postgres.

Example 8: Labels

Type this:

docker inspect --format '{{index .Config.Labels "org.testcontainers"}}' $(docker ps -q --filter ancestor=postgres:16-alpine)

You will see:

true

What it means: Marked as a test container.

Example 9: Kill the test, Ryuk cleans

Type this:

sleep 15 && docker ps -q --filter label=org.testcontainers=true | wc -l

You will see:

0

What it means: Even a crashed run leaves nothing.

Example 10: conftest.py

Type this:

import pytest
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope='session')
def pg_url():
    with PostgresContainer('postgres:16-alpine', driver=None) as pg:
        yield pg.get_connection_url()

You will see:

(file)

What it means: One container for all tests.

Example 11: Use it

Type this:

def test_insert(pg_url):
    with psycopg.connect(pg_url) as c:
        c.execute('create table if not exists t(x int)')
        c.execute('insert into t values (1)')

You will see:

(test)

What it means: Tests just ask for pg_url.

Example 12: Run many

Type this:

pytest -q tests/

You will see:

58 passed in 9.84s

What it means: One start, 58 tests.

Example 13: Fixture with Alembic

Type this:

@pytest.fixture(scope='session')
def db(pg_url):
    import subprocess, os
    env = dict(os.environ, DATABASE_URL=pg_url)
    subprocess.run(['alembic', 'upgrade', 'head'], check=True, env=env)
    return pg_url

You will see:

(conftest.py)

What it means: Real schema before any test.

Example 14: Run

Type this:

pytest -q tests/ 2>&1 | tail -2

You will see:

INFO  [alembic.runtime.migration] Running upgrade 0041 -> 0042, add rewards jsonb
58 passed in 11.02s

What it means: Migrations applied.

Example 15: A bad migration

Type this:

pytest -q tests/ 2>&1 | grep -m1 Error

You will see:

psycopg.errors.DuplicateColumn: column "points" of relation "rewards" already exists

What it means: Caught in tests, not in production.

Example 16: The test

Type this:

def test_upsert_reward(db):
    with psycopg.connect(db) as c:
        sql = "insert into rewards(user_id, meta) values (7, '{\"tier\":\"gold\"}') on conflict (user_id) do update set meta = rewards.meta || excluded.meta"
        c.execute(sql); c.execute(sql)
        assert c.execute('select count(*) from rewards').fetchone()[0] == 1

You will see:

(test)

What it means: Runs twice, still one row.

Example 17: Run

Type this:

pytest -q -k upsert

You will see:

1 passed in 5.02s

What it means: Real Postgres behaviour checked.

Example 18: Version matches production

Type this:

pytest -q -k version -s

You will see:

server_version 16.4

What it means: Same major version as production.

Example 19: Rollback fixture

Type this:

@pytest.fixture
def conn(db):
    with psycopg.connect(db) as c:
        c.execute('begin')
        yield c
        c.rollback()

You will see:

(conftest.py)

What it means: Every test starts clean.

Example 20: Two tests, same id

Type this:

pytest -q -k 'user_seven'

You will see:

2 passed in 0.31s

What it means: No duplicate key between tests.

Example 21: Random order

Type this:

pip install pytest-randomly >/dev/null && pytest -q tests/ | tail -1

You will see:

58 passed in 10.77s

What it means: Order does not matter: true isolation.

Example 22: The test

Type this:

@Testcontainers
class RewardRepoTest {
  @Container
  static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16-alpine");

  @Test void connects() throws Exception {
    try (var c = DriverManager.getConnection(pg.getJdbcUrl(), pg.getUsername(), pg.getPassword())) {
      assertTrue(c.isValid(2));
    }
  }
}

You will see:

(RewardRepoTest.java)

What it means: static means one container for the class.

Example 23: Run

Type this:

./mvnw -q test -Dtest=RewardRepoTest

You will see:

Tests run: 1, Failures: 0, Errors: 0

What it means: Passes.

Example 24: Dependency

Type this:

mvn dependency:tree | grep testcontainers

You will see:

org.testcontainers:postgresql:jar:1.20.3:test

What it means: Test scope only.

Example 25: The test

Type this:

const { PostgreSqlContainer } = require('@testcontainers/postgresql');
const { Client } = require('pg');
let pg;
beforeAll(async () => { pg = await new PostgreSqlContainer('postgres:16-alpine').start(); }, 60000);
afterAll(async () => { await pg.stop(); });
test('select 1', async () => {
  const c = new Client({ connectionString: pg.getConnectionUri() });
  await c.connect();
  expect((await c.query('select 1 as x')).rows[0].x).toBe(1);
  await c.end();
});

You will see:

(reward.test.js)

What it means: Long timeout for the first image pull.

Example 26: Run

Type this:

npx jest reward.test.js

You will see:

Tests: 1 passed, 1 total

What it means: Works.

Example 27: Install

Type this:

npm i -D @testcontainers/postgresql pg jest

You will see:

added 112 packages

What it means: Dev dependencies only.

Example 28: Jenkins stage

Type this:

stage('Integration tests') {
  agent { label 'docker' }
  steps { sh 'pip install -r requirements-dev.txt && pytest -q tests/' }
}

You will see:

(Jenkinsfile)

What it means: An agent that has Docker.

Example 29: Log

Type this:

pytest -q tests/ | tail -1

You will see:

58 passed in 14.30s

What it means: Slower on first run because of the pull.

Example 30: Pre-pull the image

Type this:

docker pull -q postgres:16-alpine

You will see:

docker.io/library/postgres:16-alpine

What it means: Put this in the agent image or a cache to save time.

Example 31: tmpfs data

Type this:

pg = PostgresContainer('postgres:16-alpine', driver=None).with_kwargs(tmpfs={'/var/lib/postgresql/data': 'rw'})

You will see:

(conftest.py)

What it means: No disk writes.

Example 32: Fewer fsyncs

Type this:

pg = pg.with_command('postgres -c fsync=off -c synchronous_commit=off')

You will see:

(conftest.py)

What it means: Fine for throwaway tests, never for production.

Example 33: Compare

Type this:

pytest -q tests/ | tail -1

You will see:

58 passed in 6.12s

What it means: From 11 seconds to 6.

Example 34: No Docker

Type this:

pytest -q 2>&1 | grep -m1 -i docker

You will see:

docker.errors.DockerException: Error while fetching server API version: Connection refused

What it means: The daemon is not reachable from the tests.

Example 35: Check the socket

Type this:

ls -l /var/run/docker.sock && docker version --format '{{.Server.Version}}'

You will see:

srw-rw---- 1 root docker 0 ... /var/run/docker.sock
27.3.1

What it means: Socket exists; user must be in the docker group.

Example 36: Remove leftovers

Type this:

docker rm -f $(docker ps -aq --filter label=org.testcontainers=true) 2>/dev/null; docker ps -aq --filter label=org.testcontainers=true | wc -l

You will see:

0

What it means: Only test containers are touched.