SYNOPSIS

use Testcontainers::Labels qw( default_labels merge_custom_labels session_id );

# Generate a session ID for this test run
my $sid = session_id();

# Get the standard labels every container should carry
my %labels = default_labels($sid);

# Safely merge user labels (rejects org.testcontainers.* overrides)
my %merged = merge_custom_labels(\%labels, { app => 'mytest' });

DESCRIPTION

Implements the Testcontainers label specification as defined by the reference implementations (Go, Java). Every container created by Testcontainers carries a set of well-known labels that identify it as managed by the framework, enable Ryuk cleanup, and record session metadata.

LABEL CONSTANTS

The following constants mirror the Go reference at internal/core/labels.go:

LABEL_BASE - org.testcontainers

Marker label. Always set to "true".

LABEL_LANG - org.testcontainers.lang

Language of the client library. Set to "perl".

LABEL_VERSION - org.testcontainers.version

Version of the Testcontainers library.

LABEL_SESSION_ID - org.testcontainers.sessionId

A unique identifier tying resources to a single test session. Used by Ryuk to determine which resources to reap.

LABEL_REAPER - org.testcontainers.reaper

Labels the Ryuk container itself.

LABEL_RYUK - org.testcontainers.ryuk

Labels the Ryuk container itself (alternate key).

LABEL_REAP - org.testcontainers.reap

When set to "true", signals that the resource should be reaped by Ryuk.

Returns a UUID v4 string that uniquely identifies the current test session. Generated lazily on first call and cached for the lifetime of the process.

Returns a hash of the standard labels that every Testcontainers-managed container should carry. If $session_id is omitted the per-process session ID is used automatically.

When the environment variable TESTCONTAINERS_RYUK_DISABLED is set to a true value, the org.testcontainers.reap label is omitted.

Merges user-supplied labels into the defaults. Croaks if any custom label key starts with org.testcontainers to prevent accidental overrides of the well-known labels.