Image Pull Policies

import org.testcontainers.images.ImagePullPolicy;
import org.testcontainers.utility.DockerImageName;

/**
 * Interface for defining when images should be pulled from a registry.
 * Implement this interface to create custom pull policies.
 */
public interface ImagePullPolicy {
    /**
     * Determine if an image should be pulled from the registry.
     *
     * @param imageName the Docker image name to check
     * @return true if the image should be pulled, false to use cached version
     */
    boolean shouldPull(DockerImageName imageName);
}

import org.testcontainers.images.PullPolicy;
import org.testcontainers.images.ImagePullPolicy;
import java.time.Duration;

/**
 * Convenience factory class for creating common ImagePullPolicy instances.
 * This is a utility class with static methods only and cannot be instantiated.
 */
@UtilityClass
public class PullPolicy {
    /**
     * Get the default pull policy.
     * If configured via testcontainers.properties (pull.policy property),
     * returns the configured policy. Otherwise returns DefaultPullPolicy.
     * The default policy pulls images only if they don't exist locally.
     *
     * @return the default or configured ImagePullPolicy
     */
    public static ImagePullPolicy defaultPolicy();

    /**
     * Get a policy that always pulls images from the registry.
     * Useful for development with 'latest' tags or when you always
     * need the most recent version of an image.
     *
     * @return AlwaysPullPolicy instance
     */
    public static ImagePullPolicy alwaysPull();

    /**
     * Get a policy that pulls images if they're older than maxAge.
     * Checks the image creation date and pulls if the local image
     * age exceeds the specified duration.
     *
     * @param maxAge maximum age before pulling a fresh copy
     * @return AgeBasedPullPolicy instance
     */
    public static ImagePullPolicy ageBased(Duration maxAge);
}

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.images.PullPolicy;
import org.testcontainers.utility.DockerImageName;

GenericContainer<?> container = new GenericContainer<>(DockerImageName.parse("redis:7.0"))
    .withImagePullPolicy(PullPolicy.defaultPolicy())
    .withExposedPorts(6379);

// Will use local redis:7.0 if available, otherwise pulls it
container.start();

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.images.PullPolicy;
import org.testcontainers.utility.DockerImageName;

// Always pull latest nginx, even if it's cached
GenericContainer<?> nginx = new GenericContainer<>(DockerImageName.parse("nginx:latest"))
    .withImagePullPolicy(PullPolicy.alwaysPull())
    .withExposedPorts(80);

nginx.start();

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.images.PullPolicy;
import org.testcontainers.utility.DockerImageName;
import java.time.Duration;

// Pull if local image is older than 7 days
GenericContainer<?> postgres = new GenericContainer<>(DockerImageName.parse("postgres:15"))
    .withImagePullPolicy(PullPolicy.ageBased(Duration.ofDays(7)))
    .withExposedPorts(5432);

postgres.start();

// Common durations
PullPolicy.ageBased(Duration.ofHours(24));   // Pull if older than 1 day
PullPolicy.ageBased(Duration.ofDays(7));     // Pull if older than 1 week
PullPolicy.ageBased(Duration.ofMinutes(30)); // Pull if older than 30 minutes

import org.testcontainers.images.AbstractImagePullPolicy;
import org.testcontainers.images.ImageData;
import org.testcontainers.utility.DockerImageName;

/**
 * Abstract base class for image pull policies.
 * Handles local image cache checking and delegates to subclasses
 * for deciding whether to pull cached images.
 */
public abstract class AbstractImagePullPolicy implements ImagePullPolicy {
    /**
     * Main shouldPull implementation that handles cache lookup.
     * Subclasses should NOT override this method.
     *
     * @param imageName the image to check
     * @return true if image should be pulled
     */
    @Override
    public boolean shouldPull(DockerImageName imageName);

    /**
     * Decide whether a locally cached image should be pulled.
     * This method is only called when the image exists locally.
     *
     * @param imageName the image name
     * @param localImageData metadata about the local image
     * @return true to pull a fresh copy, false to use cached version
     */
    protected abstract boolean shouldPullCached(DockerImageName imageName, ImageData localImageData);
}

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.images.PullPolicy;
import org.testcontainers.utility.DockerImageName;

// Container with default policy
GenericContainer<?> redis = new GenericContainer<>(DockerImageName.parse("redis:7.0"))
    .withImagePullPolicy(PullPolicy.defaultPolicy())
    .withExposedPorts(6379);

// Container that always pulls
GenericContainer<?> nginx = new GenericContainer<>(DockerImageName.parse("nginx:latest"))
    .withImagePullPolicy(PullPolicy.alwaysPull())
    .withExposedPorts(80);

// Container with age-based policy
GenericContainer<?> postgres = new GenericContainer<>(DockerImageName.parse("postgres:15"))
    .withImagePullPolicy(PullPolicy.ageBased(java.time.Duration.ofDays(7)))
    .withExposedPorts(5432);

# Use fully qualified class name of a policy implementation
pull.policy=org.testcontainers.images.AlwaysPullPolicy

# Or use custom policy
pull.policy=com.example.MyCustomPullPolicy

export TESTCONTAINERS_PULL_POLICY=org.testcontainers.images.AlwaysPullPolicy

import org.testcontainers.utility.TestcontainersConfiguration;

// Set global policy via configuration file
TestcontainersConfiguration.getInstance()
    .updateUserConfig("pull.policy", "org.testcontainers.images.AlwaysPullPolicy");

import org.testcontainers.images.ImagePullPolicy;
import org.testcontainers.utility.DockerImageName;

/**
 * Custom policy that never pulls images tagged with "snapshot".
 * Useful when snapshot images are built locally and shouldn't be pulled.
 */
public class NeverPullSnapshotPolicy implements ImagePullPolicy {
    @Override
    public boolean shouldPull(DockerImageName imageName) {
        // Never pull images tagged with "snapshot"
        if (imageName.getVersionPart().contains("snapshot")) {
            return false;
        }
        // For other images, pull if not cached
        return !isImageCached(imageName);
    }

    private boolean isImageCached(DockerImageName imageName) {
        // Check if image exists locally (simplified)
        return false; // Implement actual cache check
    }
}

import org.testcontainers.images.AbstractImagePullPolicy;
import org.testcontainers.images.ImageData;
import org.testcontainers.utility.DockerImageName;
import java.time.DayOfWeek;
import java.time.LocalDateTime;

/**
 * Custom policy that pulls images only on Mondays.
 * Ensures fresh images at the start of each week.
 */
public class WeeklyPullPolicy extends AbstractImagePullPolicy {
    @Override
    protected boolean shouldPullCached(DockerImageName imageName, ImageData localImageData) {
        // Pull if it's Monday
        return LocalDateTime.now().getDayOfWeek() == DayOfWeek.MONDAY;
    }
}

// Usage
GenericContainer<?> container = new GenericContainer<>(DockerImageName.parse("myapp:latest"))
    .withImagePullPolicy(new WeeklyPullPolicy());

import org.testcontainers.images.AbstractImagePullPolicy;
import org.testcontainers.images.ImageData;
import org.testcontainers.images.PullPolicy;
import org.testcontainers.utility.DockerImageName;
import java.time.Duration;

/**
 * Hybrid policy: always pull 'latest', age-based for other tags.
 */
public class SmartPullPolicy extends AbstractImagePullPolicy {
    private static final Duration MAX_AGE = Duration.ofDays(7);

    @Override
    protected boolean shouldPullCached(DockerImageName imageName, ImageData localImageData) {
        // Always pull 'latest' tags
        if ("latest".equals(imageName.getVersionPart())) {
            return true;
        }

        // For specific versions, use age-based logic
        Duration imageAge = Duration.between(
            localImageData.getCreatedAt(),
            java.time.Instant.now()
        );
        return imageAge.compareTo(MAX_AGE) > 0;
    }
}

// Use age-based for a balance of freshness and speed
.withImagePullPolicy(PullPolicy.ageBased(Duration.ofDays(1)))

// Use default policy (images typically pre-pulled or cached)
.withImagePullPolicy(PullPolicy.defaultPolicy())

// Always pull to test against latest dependencies
.withImagePullPolicy(PullPolicy.alwaysPull())

// Temporarily use alwaysPull to force refresh
.withImagePullPolicy(PullPolicy.alwaysPull())

// Or remove cached images manually
// docker rmi image:tag

// Switch to default policy
.withImagePullPolicy(PullPolicy.defaultPolicy())

// Or use age-based with longer duration
.withImagePullPolicy(PullPolicy.ageBased(Duration.ofDays(7)))

// Pre-pull images before running tests
// docker pull image:tag

# Verify property name and value in ~/.testcontainers.properties
pull.policy=com.example.MyCustomPullPolicy

# Ensure class is on classpath and has no-arg constructor

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.images.PullPolicy;
import org.testcontainers.utility.DockerImageName;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.junit.jupiter.api.Test;
import java.time.Duration;

@Testcontainers
public class ImagePullPolicyExample {

    // Container with default policy (use cached if available)
    @Container
    private static final GenericContainer<?> redis = new GenericContainer<>(
        DockerImageName.parse("redis:7.0")
    )
        .withImagePullPolicy(PullPolicy.defaultPolicy())
        .withExposedPorts(6379);

    // Container that always pulls (useful for 'latest' tags)
    @Container
    private static final GenericContainer<?> nginx = new GenericContainer<>(
        DockerImageName.parse("nginx:latest")
    )
        .withImagePullPolicy(PullPolicy.alwaysPull())
        .withExposedPorts(80);

    // Container with age-based policy (pull if older than 7 days)
    @Container
    private static final GenericContainer<?> postgres = new GenericContainer<>(
        DockerImageName.parse("postgres:15")
    )
        .withImagePullPolicy(PullPolicy.ageBased(Duration.ofDays(7)))
        .withExposedPorts(5432)
        .withEnv("POSTGRES_PASSWORD", "test");

    @Test
    public void testContainersWithDifferentPullPolicies() {
        // All containers are started with their respective pull policies
        assert redis.isRunning();
        assert nginx.isRunning();
        assert postgres.isRunning();
    }
}