rand #

rand generates realistic random values for Dart — names, emails, dates, IP addresses, UUIDs, lorem text, CSS colors, weighted picks — one static call each. Seed it, and every call except the cryptographic ones returns the same values on the next run. Pure Dart, all six platforms, no Flutter dependency.

Why #

Test data usually ends up as fixed strings ('John Doe', 'test@test.com') that exercise one path forever, or as a small Random helper that every project writes again. Varied data covers more cases, but a random test that fails once is hard to reproduce. rand gives you:

The helper, already written. Rand.email(), Rand.dateTime(min: a, max: b), Rand.sample(items, count: 10, weights: w) instead of code you maintain.
Failures you can replay. Give each test a random seed and print it on failure; Rand.seed(n) brings back exactly the same data.
A strict, predictable API. Ranges are half-open like Random.nextInt, default emails use reserved domains (example.com, *.test), never real ones, and invalid arguments throw instead of being quietly adjusted.

Quick start #

If only your tests use rand, add it as a dev dependency:

dart pub add dev:rand

App code uses it too (demo data, prototypes)? Run dart pub add rand instead.

A test that gets new data on every run and can still replay a failure:

import 'dart:convert';

import 'package:rand/rand.dart';
import 'package:test/test.dart';

void main() {
  // Fresh data on every run; a failing test prints the seed that replays it.
  setUp(() {
    Rand.seed();
    printOnFailure('Replay with Rand.seed(${Rand.currentSeed})');
  });

  test('a user survives a JSON round trip', () {
    final user = {'name': Rand.fullName(), 'email': Rand.email()};
    expect(jsonDecode(jsonEncode(user)), user);
  });
}

Fixed values instead? Seed with a constant. These are the values Rand.seed(42) produces:

Rand.seed(42);
Rand.fullName();  // 'Sophia Tran'
Rand.email();     // 'david88@example.com'
Rand.ipv4();      // '143.61.48.184'
Rand.password();  // 12 chars, CSPRNG — not seeded
Rand.color();     // CssColors.darkKhaki
Rand.dateTime();  // 1972-02-25 21:42:51.597617Z
// 10 draws, 'common' 100 times as likely as 'rare'
Rand.sample(['rare', 'common'], count: 10, weights: [1, 100]);

When to use it #

Test fixtures and seed data.
Mocking API responses.
Demos, prototypes, throwaway tokens.
Game prototyping (loot-box weighting, dice, color palettes).

For composing structured fixtures (User, Address, Order, paginated responses, chat history) on top of these primitives, see example/recipes.dart.

When not to use it #

Not faker. rand returns flat values. Compose typed entities yourself: User(name: Rand.fullName(), city: Rand.city()).
Not a crypto library. Rand.password() and Rand.nonce() use the platform CSPRNG, but the package's stability contract is "test data," not production secrets. Defaults may shift across major versions.
Not a UUID library. Rand.uuidV4(), uuidV7() and ulid() are seedable test IDs drawn from the non-cryptographic RNG. For production IDs use package:uuid.

API at a glance #

Everything below is a static member of Rand, apart from the RandGen class and the CssColors enum. A RandGen carries the same generators over your own Random, minus the cryptographic ones and the seeding controls.

Area	API
Seeding	`seed`, `currentSeed`, `withSeed`, `useRng`, `RandGen`
Numbers	`integer`, `float`, `latitude`, `longitude`, `charCode`
Probability	`boolean`, `nullable`
Text	`word`, `words`, `sentence`, `paragraph`, `article`
Identity and geo	`firstName`, `lastName`, `fullName`, `alias`, `city`, `geoPoint`
Networking	`email`, `ipv4`, `ipv6`, `mac`, `hex`, `semver`, `digits`, `slug`
IDs	`uuidV4`, `uuidV7`, `ulid`
Time	`dateTime`, `duration`
Collections	`element`, `enumValue`, `subset`, `shuffled`, `mapKey`, `mapValue`, `mapEntry`
Weighted sampling	`sample`
Colors	`color`, `colorDark`, `colorLight`, `CssColors`
Cryptographic tokens	`bytes`, `nonce`, `password`, `base64`, `secureCharCode`, `base62Alphabet` (`Rand` only)

Seeding and reproducibility #

rand uses two RNGs. Every non-cryptographic method draws from a replaceable Random; the cryptographic ones always use Random.secure().

import 'dart:math';

void main() {
  Rand.useRng(Random(42)); // any Random instance
  Rand.seed(42); // useRng(Random(42)), and Rand.currentSeed == 42
  Rand.useRng(Random.secure()); // global swap to a CSPRNG; clears currentSeed

  // One callback with its own seed; the global stream is untouched.
  final user = Rand.withSeed(7, () => (Rand.fullName(), Rand.email()));

  // An independent stream with the same non-crypto API.
  final gen = RandGen(Random(1));
  final name = gen.fullName();

  // One secure draw; the global RNG and currentSeed stay untouched.
  final picks = RandGen(Random.secure()).sample(['a', 'b', 'c'], count: 2);
}

useRng and seed mutate the global non-cryptographic RNG. withSeed scopes a seed to one callback: it is zone-based, so it follows awaits, nests (the inner scope wins), and never touches the global. RandGen is the non-cryptographic API as an instance over your own Random — inject it where explicit wiring beats a global; independent instances are independent streams. RandGen.seeded(1) is shorthand for RandGen(Random(1)) without importing dart:math. Cryptographic methods (password, nonce, bytes, base64, secureCharCode) live only on Rand, always use Random.secure(), and ignore all of these.

Replay a failing test #

Pick a random seed per test and print it only when the test fails:

import 'package:test/test.dart';

setUp(() {
  Rand.seed(); // random seed in [0, 2^32)
  printOnFailure('Rand seed: ${Rand.currentSeed}'); // replay with Rand.seed(n)
});

Seed in setUp, not setUpAll: each test starts from the same state whatever ran before it (--name, --test-randomize-ordering-seed).

Ranges and counts #

Every range is [min, max) half-open, like Random.nextInt and nextDouble: integer, float, dateTime, duration. An empty range (min >= max) throws ArgumentError, like nextInt(0).

Counts accept 0 and return an empty result (words, sentence, paragraph, article, bytes, subset, sample). Single-token generators — nonce, hex, digits, base64, slug — need a length of at least 1.

Numbers #

Rand.integer();                    // [0, 2^31)
Rand.integer(min: 50, max: 100);   // 50..99
Rand.float();                      // [0.0, 1.0), like nextDouble
Rand.float(min: 10, max: 20);      // [10.0, 20.0)
Rand.latitude();                   // -90..90, 5 decimal places
Rand.longitude(precision: 3);      // -180..180, 3 decimal places
Rand.charCode();                   // base62 code point (int)

integer(max: list.length) is always a valid index of a non-empty list (or just call Rand.element(list)). float's default max is 1, so float(min: 5) throws — pass a max.

Probability #

Rand.boolean();                         // 50% true
Rand.boolean(trueChance: 90);           // 90% true
Rand.boolean(trueChance: 99.9);         // 99.9% true
Rand.nullable('value');                 // 50% null, useful in fixtures
Rand.nullable('value', nullChance: 90); // 90% null

Text #

Lorem ipsum from a built-in corpus.

Rand.word();                       // 'lorem'
Rand.words(count: 5);              // 'amet consectetur adipiscing elit sed'
Rand.words(count: 3, separator: '-');
Rand.sentence();                   // 'Lorem ipsum dolor sit amet.'
Rand.sentence(count: 3);           // 3 unique sentences joined by ' '
Rand.paragraph(count: 3);          // 3 sentences joined by ' '
Rand.article(count: 5);            // 5 paragraphs separated by '\n\n'

words(count: N) and sentence(count: N) use subset — the same word/sentence never repeats in one call (corpora: 167 unique words, 856 sentences). For repeats, call word() / sentence() N times yourself, or use paragraph(count: N).

Identity and geo #

Rand.firstName();   // 'Olivia'
Rand.lastName();    // 'Thompson'
Rand.fullName();    // 'James Michael Wilson' — 0..2 weighted middle names
Rand.alias();       // 'Achilles'
Rand.city();        // 'Boston'
Rand.geoPoint();    // (lat: 42.36011, lng: -71.05891) — named record

Corpora are US/English-leaning. For locale-aware data, reach for package:faker.

Geo points are uniform in degrees, not over the sphere's area: |lat| > 60 is ~33% of draws versus ~13% of the Earth's surface, and rounding to precision gives ±90 / ±180 half the weight of other values.

Networking #

Rand.email();                       // 'olivia42@example.com'
Rand.email(domain: 'mycompany.io'); // 'james7@mycompany.io'
Rand.ipv4();                        // '203.0.113.42'
Rand.ipv6();                        // '2001:0db8:85a3:0000:0000:8a2e:0370:7334'
Rand.mac();                         // '3a:5f:9c:8e:2d:71'
Rand.mac(separator: '-');           // '3a-5f-9c-8e-2d-71'
Rand.hex(length: 40);               // git-SHA-shaped opaque hex
Rand.semver();                      // '3.7.42'
Rand.digits();                      // '047215'
Rand.slug();                        // 'lorem-ipsum-dolor'

email picks its default domain from a built-in list of RFC 2606 reserved names (example.com, example.org, example.net and *.test domains) — safe to ship in fixtures without collision risk. ipv4 is not filtered for reserved ranges; compose your own filter if you need only routable addresses. ipv6 is returned in full form (no :: collapse) so fixture length stays stable. hex is general-purpose lowercase hex — git SHAs, ETags, opaque content hashes. All of these use the non-secure RNG and are reproducible under Rand.seed.

IDs #

final instant = DateTime.utc(2026, 10, 3, 12, 34, 56, 789);
Rand.uuidV4();                     // '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
Rand.uuidV7(time: instant);        // '01a101c2-a895-7…'
Rand.uuidV7(time: DateTime.now()); // live clock
Rand.ulid(time: instant);          // '01M40W5A4N…', 26 chars

All three draw from the non-cryptographic RNG, so they reproduce under seed, withSeed and RandGen. uuidV7 and ulid take a required time: a fixed instant keeps the whole ID stable for snapshot tests, DateTime.now() gives a live clock. v7 and ULID sort by time across milliseconds but are not monotonic within one; a time before 1970 or past year 10889 throws. Production IDs → package:uuid.

Time #

Rand.dateTime();                              // [1970-01-01, 2038-01-01) UTC
Rand.dateTime(min: DateTime.utc(2020), max: DateTime.utc(2025));
Rand.duration(max: const Duration(days: 30)); // 0 to 30 days
Rand.duration(min: const Duration(days: 1), max: const Duration(days: 30));

dateTime and duration are [min, max) half-open and throw ArgumentError on an empty or reversed range — including dateTime(min: t) with t at or after 2038-01-01 and no max. dateTime always returns UTC.

Collections #

enum Status { active, suspended, deleted }
final fruits = ['apple', 'orange', 'lemon', 'grape', 'kiwi'];
final scores = {'Alice': 95, 'Bob': 87};

Rand.element(fruits);              // 'orange'
Rand.enumValue(Status.values);     // Status.suspended — typed enum draw
Rand.subset({1, 2, 3, 4, 5}, count: 3); // {2, 5, 1} — unique elements
Rand.shuffled(fruits);             // ['kiwi', 'grape', 'apple', ...] — copy
Rand.mapKey(scores);               // 'Bob'
Rand.mapValue(scores);             // 95
Rand.mapEntry(scores);             // MapEntry('Alice', 95)

Pick the right call:

Need	Use
One element	`element(iterable)`
One enum member	`enumValue(MyEnum.values)`
N unique elements	`subset(set, count: N)`
N elements, repeats okay	`sample(list, count: N)`
N elements with weighted frequency	`sample(..., weights: [...])`
Whole list, reordered	`shuffled(list)`
One key / value / entry of a Map	`mapKey` / `mapValue` / `mapEntry`

subset requires Set<T> — dedupe explicitly with .toSet() if your source has duplicates.

Weighted sampling #

sample draws with replacement, optionally weighted.

// Loot box: weights are relative, so 1 : 10 : 100 is ~0.9% / ~9% / ~90%
final loot = Rand.sample(
  ['Legendary', 'Rare', 'Common'],
  count: 100,
  weights: [1, 10, 100],
);

// Equal probability — drop weights
final dice = Rand.sample([1, 2, 3, 4, 5, 6], count: 10);

weights.length must equal from.length. An empty from throws StateError unless count is 0. For a secure sample, draw from your own generator — RandGen(Random.secure()).sample(...) — so the global RNG and Rand.currentSeed stay untouched.

Colors #

final c = Rand.color();  // CssColors.coral
final name = c.name;     // 'coral'
final argb = c.argb;     // 0xFFFF7F50 — ARGB packed int
final isDark = c.isDark; // computed via YIQ luminance

Rand.colorDark();        // dark colors only — good for light backgrounds
Rand.colorLight();       // light colors only — good for dark backgrounds

148 CSS named variants. The argb int is Flutter-friendly: Color(c.argb) works without conversion. isDark is a CssColors getter — computed from argb via the YIQ luminance formula, not stored on the enum. Use it (or your own contrast helper, e.g. fluiver's Color.contrastText) to pick a foreground.

Cryptographic tokens #

Rand.bytes(length: 32);      // Uint8List, always Random.secure()
Rand.nonce();                // 16-char base62, always Random.secure()
Rand.nonce(length: 32);
Rand.password();             // 12-char mixed-charset, always Random.secure()
Rand.password(length: 20, symbols: false);
Rand.base64();               // 16 bytes encoded, always Random.secure()
Rand.secureCharCode();       // base62 code point, always Random.secure()

// The 62 characters nonce, secureCharCode and charCode draw from
const alphabet = Rand.base62Alphabet; // 0-9, then A-Z, then a-z

Three rules:

Seed doesn't reach secure methods. Rand.seed(42); Rand.password() is fresh CSPRNG output every call. For reproducible token tests, generate them from your own Random instance.
Don't ship rand-generated tokens as production secrets. The RNG is correct; the package contract is "test data." Defaults can shift across major versions. Use package:cryptography or your platform's keystore for real secrets.
bytes and nonce are always secure post-v4 — the secure: parameter is gone.

Crypto methods throw under dart test -p node: dart2js has no secure RNG there. Every other method works.

Pitfalls #

❌	✅
`Rand.integer(min: 1, max: 6)` for a die roll — `max` is exclusive, never 6	`Rand.integer(min: 1, max: 7)`
`Rand.float(min: 5)` — default `max` is 1, so it throws	Pass both bounds: `Rand.float(min: 5, max: 10)`
`Rand.integer(max: list.length)` on a list that may be empty — `[0, 0)` is empty and throws	Guard with `list.isNotEmpty`, or call `Rand.element(list)`
`Rand.seed(42); Rand.password()` — seed never reaches CSPRNG	Build deterministic tokens from your own `Random(42)`
`Rand.subset([1, 2, 2], count: 2)` — compile error: `subset` takes a `Set<T>`	Pass a set: `Rand.subset({1, 2}, count: 2)`, or dedupe with `.toSet()`
Shipping `Rand.nonce` / `Rand.password` as production secrets	Use `package:cryptography` or a platform keystore
`setUpAll(() => Rand.seed(42))`	Use `setUp` — each test starts from the same state whatever ran before it (`--name`, `--test-randomize-ordering-seed`)
`list..shuffle()` to "get a random order" without keeping the original	`Rand.shuffled(list)` — non-mutating copy

Agent skill #

This package ships an agent skill in skills/rand-test-data/. Install it into your project's agent config with:

dart run skills@ get --package rand --all

Add --agent <name> (claude, cursor, codex, copilot, …) when no agent config is detected.

Contributing #

See CONTRIBUTING.md.

License #

MIT — see LICENSE.

rand 5.0.1
rand: ^5.0.1 copied to clipboard

Metadata

rand #

Why #

Quick start #

When to use it #

When not to use it #

API at a glance #

Seeding and reproducibility #

Replay a failing test #

Ranges and counts #

Numbers #

Probability #

Text #

Identity and geo #

Networking #

IDs #

Time #

Collections #

Weighted sampling #

Colors #

Cryptographic tokens #

Pitfalls #

Agent skill #

Contributing #

License #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

More

rand 5.0.1 rand: ^5.0.1 copied to clipboard

Metadata

rand #

Why #

Quick start #

When to use it #

When not to use it #

API at a glance #

Seeding and reproducibility #

Replay a failing test #

Ranges and counts #

Numbers #

Probability #

Text #

Identity and geo #

Networking #

IDs #

Time #

Collections #

Weighted sampling #

Colors #

Cryptographic tokens #

Pitfalls #

Agent skill #

Contributing #

License #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

More

rand 5.0.1
rand: ^5.0.1 copied to clipboard