randkit

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: MIT Imports: 3 Imported by: 0

README

The randkit package

randkit generates random test fixtures using the automatically-seeded global PRNG from math/rand/v2. Tests that rely on hardcoded values can accidentally pass for the wrong reason; randkit eliminates that class of false confidence.

String generation

Str

Str returns a random string. With no options it generates ten random letters [a-zA-Z]:

fmt.Println(randkit.Str(randkit.WithSeed(1)))
// Output:
// qLKZasgepC

Use WithLen to change the length:

fmt.Println(randkit.Str(randkit.WithSeed(1), randkit.WithLen(6)))
// Output:
// qLKZas

Use WithChars to restrict or expand the character set. The built-in constants Letters, Uppercase, Lowercase, and Digits can be composed freely:

s := randkit.Str(
    randkit.WithChars(randkit.Digits),
    randkit.WithLen(8),
    randkit.WithSeed(1),
)
fmt.Println(s)
// Output:
// 37790310

Use WithPrefix and WithSuffix (or WithExt, an alias for WithSuffix) to add fixed text around the random part:

s := randkit.Str(
    randkit.WithPrefix("test-"),
    randkit.WithSuffix("-end"),
    randkit.WithLen(6),
    randkit.WithSeed(1),
)
fmt.Println(s)
// Output:
// test-qLKZas-end

File names

FileName

FileName returns a random file path inside the given directory. The default name is seven letters with the prefix "file-" and the extension ".txt":

fmt.Println(randkit.FileName("/tmp", randkit.WithSeed(1)))
// Output:
// /tmp/file-qLKZasg.txt

Use WithExt to change the extension:

name := randkit.FileName("/tmp", randkit.WithExt(".json"), randkit.WithSeed(1))
fmt.Println(name)
// Output:
// /tmp/file-qLKZasg.json

Integers

Int

Int returns a uniform random integer in the closed range [1, max]:

fmt.Println(randkit.Int(100, randkit.WithSeed(1)))
// Output:
// 32

Passwords

Password

Password returns an n-character string drawn from letters and digits. No special characters are included:

fmt.Println(randkit.Password(16, randkit.WithSeed(1)))
// Output:
// tSR9avhesITXkYun

Deterministic output

WithSeed

WithSeed sets this call's source to a deterministic ChaCha8 PRNG seeded by the given seed, making the output reproducible for a given seed. Use it when a test needs to assert exact generated values:

func TestMyFeature(t *testing.T) {
    name := randkit.Str(randkit.WithSeed(42))
    // name is always "uAfUWlGAxu" for seed 42
    assert.Equal(t, "uAfUWlGAxu", name)
}

Warning: WithSeed is intended for tests only. Never use it in production code — the output is fully predictable from the seed and provides no security guarantees whatsoever.

Character set constants

Constant Value
Uppercase "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
Lowercase "abcdefghijklmnopqrstuvwxyz"
Letters Lowercase + Uppercase
Digits "0123456789"

Combine them freely with WithChars:

// Letters and digits only.
s := randkit.Str(randkit.WithChars(randkit.Letters, randkit.Digits))

// Digits only, length 6.
pin := randkit.Str(randkit.WithChars(randkit.Digits), randkit.WithLen(6))

Documentation

Overview

Package randkit provides random test helpers for generating strings, file names, identifiers, and other test fixtures. The default source is math/rand/v2's automatically-seeded global PRNG, which is fast and sufficiently random for test use. Pass WithSeed to switch to a deterministic source with stable output.

Index

Examples

Constants

View Source 
const (
	// Uppercase is the list of uppercase letters.
	Uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

	// Lowercase is the list of lowercase letters.
	Lowercase = "abcdefghijklmnopqrstuvwxyz"

	// Letters is a list of lowercase and uppercase letters.
	Letters = Lowercase + Uppercase

	// Digits is a list of digits 0 to 9.
	Digits = "0123456789"
)

Character sets used to generate random strings.

Variables

This section is empty.

Functions

func FileName 

func FileName(dir string, opts ...func(*options)) string

FileName returns a random file name. By default, the file name is 7 letters long [a-zA-Z] with the prefix "file-" and extension ".txt".

Example 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	fmt.Println(randkit.FileName("/tmp", randkit.WithSeed(1)))
}

Output:
/tmp/file-qLKZasg.txt
Example (WithExt) 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	name := randkit.FileName("/tmp", randkit.WithExt(".json"), randkit.WithSeed(1))
	fmt.Println(name)
}

Output:
/tmp/file-qLKZasg.json

func Int 

func Int(maximum int, opts ...func(*options)) int

Int generates a random integer in the range [1, max]. It panics if maximum is not positive.

Example 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	fmt.Println(randkit.Int(100, randkit.WithSeed(1)))
}

Output:
32

func Password 

func Password(n int, opts ...func(*options)) string

Password returns an n-character random password drawn from letters [a-zA-Z] and digits [0-9]. No special characters are included.

Example 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	fmt.Println(randkit.Password(16, randkit.WithSeed(1)))
}

Output:
tSR9avhesITXkYun

func Str 

func Str(opts ...func(*options)) string

Str returns a random string based on provided options. When no options are given, the generated string will be 10 characters long containing only letters. It panics if the character set is empty (e.g. WithChars("")).

Example 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	fmt.Println(randkit.Str(randkit.WithSeed(1)))
}

Output:
qLKZasgepC
Example (WithChars) 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	s := randkit.Str(
		randkit.WithChars(randkit.Digits),
		randkit.WithLen(8),
		randkit.WithSeed(1),
	)
	fmt.Println(s)
}

Output:
37790310
Example (WithLen) 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	fmt.Println(randkit.Str(randkit.WithSeed(1), randkit.WithLen(6)))
}

Output:
qLKZas
Example (WithPrefixSuffix) 
package main

import (
	"fmt"

	"github.com/ctx42/testkit/pkg/randkit"
)

func main() {
	s := randkit.Str(
		randkit.WithPrefix("test-"),
		randkit.WithSuffix("-end"),
		randkit.WithLen(6),
		randkit.WithSeed(1),
	)
	fmt.Println(s)
}

Output:
test-qLKZas-end

func WithChars 

func WithChars(list ...string) func(*options)

WithChars is a Str option setting the list of characters to use when generating random strings. All passed strings are concatenated in the order they were passed.

func WithExt 

func WithExt(ext string) func(*options)

WithExt is a Str option alias for WithSuffix.

func WithLen 

func WithLen(n int) func(*options)

WithLen is a Str option setting the length for the generated string.

func WithPrefix 

func WithPrefix(prefix string) func(*options)

WithPrefix is a Str option setting prefix for generated strings.

func WithSeed added in v0.4.0 

func WithSeed(seed int64) func(*options)

WithSeed sets this call's source to a deterministic ChaCha8 PRNG seeded by seed. Use only when a test must assert exact generated values — never in production code where unpredictability is required.

func WithSuffix 

func WithSuffix(suffix string) func(*options)

WithSuffix is a Str option setting suffix for generated strings.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.