Property-based testing.

01 / The idea

Two examples can pass while the rule is still broken.

A title normalizer is a good small boundary. Callers want a URL-safe slug, not a title with punctuation and whitespace decisions scattered through links, database keys, and pages. The starting implementation trims, lowercases, and replaces whitespace. It works for the examples the first caller wrote.

Then a generated title arrives as !!!. The function returns !!!. Nothing in the two examples asked whether the output uses an allowed alphabet, whether the operation is idempotent, or whether separators repeat.

A property-based test checks a rule against many generated inputs, then shrinks the first failure into an explanation.

// The first version handles the two examples everyone started with.
export function directSlug(title: string): string {
	return title.trim().toLowerCase().replace(/\s+/g, '-');
}

02 / See the shape

Separate the function, the property, and the search.

The direct function is the system under test. A property is a predicate over its input and output. A generator supplies inputs, a runner stops at the first failure, and a shrinker preserves that failure while removing irrelevant detail.

Switch through the forms to see the mechanism grow: the properties and fixed implementation, the generator, shrinker, and runner, then the generated call site. TypeScript and Go use the same title cases and the same failure.

export const properties = [
	{
		name: 'output uses slug characters',
		check: (slugger: Slugger, input: string) => {
			const output = slugger(input);
			if (input.length === 0) return output === '' || output === 'untitled';
			return output === 'untitled' || /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(output);
		}
	},
	{
		name: 'slugging is idempotent',
		check: (slugger: Slugger, input: string) => slugger(slugger(input)) === slugger(input)
	},
	{
		name: 'output has no repeated separators',
		check: (slugger: Slugger, input: string) => !slugger(input).includes('--')
	}
] as const;

export function slugify(title: string): string {
	let output = '';
	let needsSeparator = false;
	for (const character of title.toLowerCase()) {
		if (/^[a-z0-9]$/.test(character)) {
			if (needsSeparator && output) output += '-';
			output += character;
			needsSeparator = false;
		} else if (output) {
			needsSeparator = true;
		}
	}
	return output || 'untitled';
}

type Property struct {
	Name  string
	Check func(Slugger, string) bool
}

var properties = []Property{
	{
		Name: "output uses slug characters",
		Check: func(slugger Slugger, input string) bool {
			output := slugger(input)
			if input == "" {
				return output == "" || output == "untitled"
			}
			if output == "untitled" {
				return true
			}
			if output == "" {
				return false
			}
			for index, character := range output {
				if character == '-' {
					if index == 0 || index == len(output)-1 || output[index-1] == '-' {
						return false
					}
					continue
				}
				if !(character >= 'a' && character <= 'z') && !(character >= '0' && character <= '9') {
					return false
				}
			}
			return true
		},
	},
	{
		Name:  "slugging is idempotent",
		Check: func(slugger Slugger, input string) bool { return slugger(slugger(input)) == slugger(input) },
	},
	{
		Name:  "output has no repeated separators",
		Check: func(slugger Slugger, input string) bool { return !strings.Contains(slugger(input), "--") },
	},
}

func Slugify(title string) string {
	var builder strings.Builder
	pendingSeparator := false
	for _, character := range strings.ToLower(title) {
		ascii := (character >= 'a' && character <= 'z') || (character >= '0' && character <= '9')
		if ascii {
			if pendingSeparator && builder.Len() > 0 {
				builder.WriteByte('-')
			}
			builder.WriteRune(character)
			pendingSeparator = false
		} else if builder.Len() > 0 {
			pendingSeparator = true
		}
	}
	if builder.Len() == 0 {
		return "untitled"
	}
	return builder.String()
}

type Property struct {
	Name  string
	Check func(Slugger, string) bool
}

var properties = []Property{
	{
		Name: "output uses slug characters",
		Check: func(slugger Slugger, input string) bool {
			output := slugger(input)
			if input == "" {
				return output == "" || output == "untitled"
			}
			if output == "untitled" {
				return true
			}
			if output == "" {
				return false
			}
			for index, character := range output {
				if character == '-' {
					if index == 0 || index == len(output)-1 || output[index-1] == '-' {
						return false
					}
					continue
				}
				if !(character >= 'a' && character <= 'z') && !(character >= '0' && character <= '9') {
					return false
				}
			}
			return true
		},
	},
	{
		Name:  "slugging is idempotent",
		Check: func(slugger Slugger, input string) bool { return slugger(slugger(input)) == slugger(input) },
	},
	{
		Name:  "output has no repeated separators",
		Check: func(slugger Slugger, input string) bool { return !strings.Contains(slugger(input), "--") },
	},
}

func Slugify(title string) string {
	var builder strings.Builder
	pendingSeparator := false
	for _, character := range strings.ToLower(title) {
		ascii := (character >= 'a' && character <= 'z') || (character >= '0' && character <= '9')
		if ascii {
			if pendingSeparator && builder.Len() > 0 {
				builder.WriteByte('-')
			}
			builder.WriteRune(character)
			pendingSeparator = false
		} else if builder.Len() > 0 {
			pendingSeparator = true
		}
	}
	if builder.Len() == 0 {
		return "untitled"
	}
	return builder.String()
}

03 / Follow the failure

Watch the test earn a smaller explanation.

The frames come from the slugger and property runner above. First the named examples pass. Then a deterministic generator finds !!!. The shrinker tries smaller strings while the property remains false and stops at !. Finally the corrected slugger passes the same generated inputs.

What generation buys you

Property-based testing adds a search strategy to the claim you already named.

04 / Try a decision

Choose what to do with the surprising input.

A generated failure is evidence, not an automatic verdict. Decide whether it exposes the rule, the generator, or a property that was too strong.

05 / Give it a real job

Keep the claim independent from the test data.

The slugger can be pure and cheap to run, so its properties belong close to the transformation. The application still owns the URL policy and the UI receives a canonical projection. A generated suite should have a reproducible seed, a bounded run, useful failure output, and a path for promoting durable failures into examples.

Do not confuse many generated inputs with good coverage. Review what the generator can produce, what it cannot produce, and whether shrinking preserves the meaning of the failure. If the property says “safe URL slug,” the test should make that rule visible in both the assertion and the failure report.

type Project = { title: string; slug: string };
type ProjectApp = { getProject(projectId: string): Project | null };

export function ProjectLink({ app, projectId }: { app: ProjectApp; projectId: string }) {
	const project = app.getProject(projectId);
	if (!project) return <span>Project not found</span>;
	return <a href={`/projects/${project.slug}`}>{project.title}</a>;
}

06 / Recognize it elsewhere

Many everyday operations have properties worth exploring.

Look for a relation that should hold across inputs, not just one expected output.

07 / Already in your toolbox

Test libraries provide the loop; you provide the model.

Vitest’s assertions can check each generated result, Go’s testing package can report the seed and input, and a small generator can be an ordinary function. Go also ships two property tools: testing/quick’s quick.Check calls a property with random arguments, and native fuzzing (testing.F with f.Fuzz, run by go test -fuzz) mutates inputs and minimizes a failing one. In TypeScript, a property-testing library supplies the same generator and shrinker roles. None of them knows whether your property is meaningful.

08 / The parts to watch

A generator can create noise as easily as insight.

09 / Make the call

Use generation when the space is broad and the rule is stable.

Reach for examples when the named scenario is the clearest specification.

Reach for properties when a stable rule should hold across a wide, deliberate input space.

10 / Take the idea with you

Explain the slug bug without saying “property-based.”

“Across a dozen titles, most of them generated, we checked that every slug uses only letters, digits, and single hyphens, and that slugging a slug changes nothing. One title came back as !!!, and the smallest title that still failed was !.” That tells a reviewer what was checked and what broke. When they want the words, they are property, generator, and shrinking.

Before moving on, jot down the three properties the slugger has to keep, why ! is a better clue than !!!, and one function in your own code with a rule you could state for every input. A date formatter or a price parser counts.