Generators

A generator block declares a named source of faker data. Calling generate("<name>") from any expression returns a value produced by that generator. Output is deterministic for a given seed, see Determinism below.

generator "<type>" "<name>" {
  # type-specific attributes
}

The first label is the generator type (one of seventeen built-ins). The second is the name you reference from generate(...).

Available types

Type	Returns	Use for
email	string	Test email addresses
password	string	Throwaway passwords with configurable policy
timezone	string	IANA timezone identifiers
locale	string	BCP-47 locale tags
person	object	First name, last name, gender, full name
mac_address	string	MAC addresses
bytes	string (hex / base64)	Random byte payloads
date	string (YYYY-MM-DD)	Replayable calendar dates (birth, contract)
datetime	string (RFC3339 UTC)	Replayable timestamps (publication, events)
unix_time	number (int64 seconds)	Replayable Unix timestamps
siren	string (9 digits)	French SIREN business identifier (Luhn)
siret	string (14 digits)	French SIRET establishment identifier (Luhn)
ein	string (NN-NNNNNNN)	US Employer Identification Number
duns	string (9 digits)	Dun & Bradstreet number
lei	string (20 alphanumeric)	ISO 17442 Legal Entity Identifier
vat_number	string	EU VAT registration number
euid	string	BRIS EU Unique Identifier

email

generator "email" "user_email" {
  prefix = "qa-"          // optional, prepended after the random local-part
  domain = "example.com"  // optional, defaults to a faker domain
}

Attribute	Type	Default	Notes
prefix	string	""	Prepended to the local-part for filtering.
domain	string	faker default	Overrides the random domain.

generate("user_email")   // "[email protected]"

password

generator "password" "strong_password" {
  length      = 16
  min_upper   = 1
  min_lower   = 1
  min_digit   = 1
  min_special = 1
  specials    = "!@#$%^&*"
}

Attribute	Type	Default	Notes
length	number	12	Total length of the generated password.
min_upper	number	0	Minimum count of uppercase letters.
min_lower	number	0	Minimum count of lowercase letters.
min_digit	number	0	Minimum count of digits.
min_special	number	0	Minimum count of characters from the specials alphabet.
specials	string	a default punctuation set	Characters considered “special” for min_special.

The sum of min_* constraints must not exceed length; the parser rejects impossible combinations.

timezone

generator "timezone" "tz" {}

No options. Returns an IANA timezone string (e.g. "America/New_York", "Europe/Paris").

locale

generator "locale" "loc" {
  separator = "-"   // "-" → "en-US"; "_" → "en_US"; default "-"
}

Attribute	Type	Default	Notes
separator	string	"-"	Glue character between language and region segments.

Returns a BCP-47 tag (e.g. "en-US", "fr_FR").

person

generator "person" "demo_person" {
  gender = "female"   // optional: "male", "female", omit for random
}

Attribute	Type	Default	Notes
gender	string	random	Constrain to "male" or "female".

Returns an object:

generate("demo_person")
// {
//   first_name = "Alice"
//   last_name  = "Martin"
//   gender     = "female"
//   name       = "Alice Martin"
// }

mac_address

generator "mac_address" "mac" {
  prefix    = "aa:bb"   // optional, fixed leading octets
  separator = "-"       // optional, ":" | "-" | "" (default ":")
  lowercase = true      // optional, default false (uppercase hex)
}

Attribute	Type	Default	Notes
prefix	string	""	Fixed leading octets (with separator).
separator	string	":"	Glue between octets. Use "" for compact.
lowercase	bool	false	Emit lowercase hex.

bytes

generator "bytes" "trace_id" {
  length   = 8        // optional, default 16, count of bytes (not hex chars)
  encoding = "hex"    // optional, "hex" (default) | "base64"
}

Attribute	Type	Default	Notes
length	number	16	Number of bytes generated (before encoding).
encoding	string	"hex"	Output encoding. "hex" doubles length; "base64" is shorter.

generate("trace_id")   // "7f3a4c91" (length=4 hex)

date

Replayable calendar dates, formatted as YYYY-MM-DD. Both bounds are required and inclusive; they are normalized to whole UTC days (any clock component is ignored). from == to always returns that exact date.

generator "date" "birth_date" {
  from = "1980-01-01"   // required, YYYY-MM-DD
  to   = "2006-12-31"   // required, YYYY-MM-DD
}

Attribute	Type	Default	Notes
from	string	—	Required. Inclusive lower bound (UTC).
to	string	—	Required. Inclusive upper bound (UTC).

generate("birth_date")   // "1994-07-18"

datetime

Replayable timestamps as RFC3339 UTC strings (always Z). Both bounds are required and inclusive, compared at second granularity. Inputs are RFC3339 (with a timezone offset) and converted to UTC; the output is always UTC.

generator "datetime" "published_at" {
  from = "2024-01-01T00:00:00Z"   // required, RFC3339
  to   = "2024-12-31T23:59:59Z"   // required, RFC3339
}

Attribute	Type	Default	Notes
from	string	—	Required. Inclusive lower bound (RFC3339).
to	string	—	Required. Inclusive upper bound (RFC3339).

generate("published_at")   // "2024-07-18T12:34:56Z"

unix_time

Replayable Unix timestamps as a number (int64 seconds), not a string, handy for APIs that expect an epoch. Both bounds are required, inclusive, RFC3339, compared at second granularity in UTC.

generator "unix_time" "event_ts" {
  from = "2024-01-01T00:00:00Z"   // required, RFC3339
  to   = "2024-12-31T23:59:59Z"   // required, RFC3339
}

Attribute	Type	Default	Notes
from	string	—	Required. Inclusive lower bound (RFC3339).
to	string	—	Required. Inclusive upper bound (RFC3339).

json = {
  created_at = generate("event_ts")   // 1721306096 (number)
}

siren

French SIREN business identifier: 9 decimal digits with a valid Luhn check digit. No attributes.

generator "siren" "company_siren" {}

generate("company_siren")   // "552100554"

siret

French SIRET establishment identifier: 14 decimal digits with a valid Luhn check digit. The first 9 digits form a Luhn-valid SIREN. No attributes.

generator "siret" "company_siret" {}

generate("company_siret")   // "55210055400024"

ein

US Employer Identification Number formatted as NN-NNNNNNN. The two-digit prefix is drawn from the IRS published campus code list; the seven-digit body is random with no published checksum. No attributes.

generator "ein" "company_ein" {}

generate("company_ein")   // "47-8392016"

duns

Dun & Bradstreet DUNS number: 9 decimal digits, format only (no public checksum). No attributes.

generator "duns" "company_duns" {}

generate("company_duns")   // "804613259"

lei

ISO 17442 Legal Entity Identifier: 20 alphanumeric characters laid out as a 4-character LOU prefix, two reserved zeroes, a 12-character entity code, and a 2-digit ISO 7064 mod 97-10 check. No attributes.

generator "lei" "company_lei" {}

generate("company_lei")   // "Q8B400X1NLEZ6V3K7C82"

vat_number

EU VAT registration number. Each country uses its own algorithm: Luhn for IT, mod 97 for FR and BE, mod 11 for PT and SK, format-only for the remaining 22 EU member states (correct length and charset, no checksum).

generator "vat_number" "company_vat" {
  country = "FR"   // optional, ISO 3166-1 alpha-2 EU member code
}

Attribute	Type	Default	Notes
country	string	random EU member	Forces the country prefix (AT, BE, BG, CY, CZ, DE, DK, EE, EL, ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK). Empty or unknown values fall back to a random EU member.

generate("company_vat")   // "FR55552100554"

euid

BRIS-style EU Unique Identifier per Regulation (EU) 2015/884. The value has the shape CC.RegisterID.EntityID.Check where Check is an ISO 7064 mod 97-10 over the unpunctuated payload.

generator "euid" "company_euid" {
  country = "FR"   // optional, ISO 3166-1 alpha-2 EU member code
}

Attribute	Type	Default	Notes
country	string	random EU member	Forces the country prefix. Empty or unknown values fall back to a random EU member.

generate("company_euid")   // "FR.RCS.552100554.47"

Determinism

Every generate(...) call mixes:

• the global --seed
• the scenario name
• the step name
• the generator name
• the expression path (where in the step body the call lives)

So two calls to the same generator in the same step produce different values, the expression path differs. To reuse a generated value (for example, a password and its confirmation field), generate it once into a vars or capture block and reference that:

step "http" "register" {
  vars {
    password = generate("strong_password")
  }

  request {
    body {
      json = {
        password         = vars.password
        password_confirm = vars.password   // same value
      }
    }
  }
}

Identical runs produce identical values regardless of --parallel, regardless of retry attempts. This is the core property that makes Tales suites replayable. See the Deterministic test data guide for more.

Wall-clock time is intentionally non-deterministic

now_unix() and now_rfc3339() are not generators, they read the wall clock and return a different value every call. When you need a stable timestamp inside a step, capture it once in a vars block: vars { ts = now_unix() }.

Use now_unix() / now_rfc3339() for live protocol values that must reflect real time (request signatures, TOTP windows). Use the date / datetime / unix_time generators when you want replayable fake timestamps that stay stable for a given --seed.