GenRocket (2): data patterns and a hands-on build

Beyond the building blocks of GenRocket (the overview, domains, attributes and generators, receivers and scenarios), the question is which values a generator should produce so that tests find bugs.

The bugs live at the edges: an order total of exactly 0.00 or 999999.99, a customer exactly 18 years old, an empty email, a phone number with a digit too few. Testers call these deliberate shapes data patterns. The patterns covered are sequential, random, boundary and edge cases, and null. Each gets a plain-words explanation with a ShopSphere example, then how GenRocket does it with documented generators, then a coverage table and a boundary-value lab. The next chapter uses several of these patterns in a full hands-on lab.

7.1 Words to know first

Positive test

A test that feeds the app data it should accept, to check it works. Example: a valid order of 49.99.

Negative test

A test that feeds the app data it should reject or handle gracefully, to check it fails safely. Example: an order total of -5.00.

Sequential data

Values that follow a fixed order, such as 1, 2, 3, 4. The usual choice for ids and numbered records.

Random data

Values picked unpredictably from a set or range. Good for realistic variety.

Seed

A starting number for the random picker. Same seed in, same "random" values out, every run. This is how random data becomes repeatable.

Boundary value

A value at, just below or just above the limit of what is allowed. The limit is the "boundary".

Edge case

A rare or unusual situation outside the typical pattern, such as a name longer than the column allows. GenRocket's own definition is "a rare or unexpected scenario outside the typical usage pattern".

Null

"No value at all" in a database column. Different from an empty string, which is a value that happens to contain zero characters.

7.2 Why test data needs patterns

A vending machine tested only with the exact price always passes; bugs appear with one coin too few, one too many, or none. Software is the same: defects hide at a limit, an empty field or a rare combination. So testing needs typical data (positive tests: looks real, proves the main flows) and tricky data (negative and edge tests: sits on the rules, proves the app rejects bad input safely). A production copy is poor at the second kind: it may hold no order of exactly 0.00 and no 17-year-old customer. With synthetic data you decide what exists.

GenRocket's CI/CD page says its web platform can design "any form of test data (positive, negative, patterns, permutations, boundary values, dynamic, load, etc.)" for a data model (Automating Data Generation using CI/CD Pipeline).

7.2.1 The ShopSphere patterns we will build

The examples use the fictional ShopSphere tables. The table lists the patterns wanted and where each is built.

7.2.2 How GenRocket thinks about a pattern

In GenRocket a pattern is a generator choice plus its parameters on an attribute; there is no separate "pattern" switch. You pick a generator (see the chapter on domains, attributes and generators), set its parameters and read the Preview pane. Generators only create raw values; receivers format them. Three mechanisms cover this section: one generator with parameters (RangeGen, RandomGen, ListGen), several generators linked in one attribute, and attribute settings such as % Null that sit outside the generator. The help centre says GenRocket has over 765 generators, so only the relevant ones are covered.

7.2.3 What the vendor says patterns are for

In its 2022 overview video, GenRocket's CEO says masked copies of production data leave "data gaps" that enterprise customers report: no unique data, no negative data, not every permutation, too little volume, nothing in a required condition. His answer is data designed to order: positive and negative data, unique permutations (every useful combination of values), and stateful data (rows in a particular condition, such as an order already shipped), always with referential integrity, shaped by rules and delivered in any volume. In the 2020 webinar GenRocket's CTO adds a design principle: most generators do not produce purely random values, because random data is hard to test with. They produce patterns, and linked generators combine them (section 6.18.12). These are the vendor's claims about its own product. Sequential, weighted and conditional data are the patterns; boundary, edge, null and permutation data are the tricky cases. The concepts chapter lists the same coverage in tool-neutral terms.

7.3 Sequential data

7.3.1 In plain words

Sequential data follows a fixed, predictable order: 1, 2, 3, 4, like numbered tickets at a bakery counter.

Testers want sequential data in three places:

• Primary keys. A primary key must be unique, so counting up is the simplest safe pattern. ShopSphere's customer_id values 1001, 1002, 1003 are sequential.
• Numbered records. Order numbers such as ORD-1001, ORD-1002, where you want to look at row 5 and know exactly what should be there.
• Predictable walks. A list of statuses walked in order (Pending, Shipped, Delivered) so a test can assume which row has which status.

Sequential data is easy to read when a test fails, but looks nothing like real life, so mix it with random data for other columns.

7.3.2 RangeGen: counting up (and down)

The generator for counting is RangeGen. The help page says it "produces an increasing value from startRange to endRange", or to long.MAX_VALUE when no end range is given, and that "once the endRange has been reached, the value is reset to the startRange" (RangeGen help page). The page also notes it can be set to start at a number other than 1, for example to continue a database's primary keys. The 2020 webinar demo shows the pattern live: the id counts up from 1,000, and changing the jump from 1 to 3 makes the sequence step by three (section 6.18.11).

The help page shows five worked examples. Four of them follow, each with the official screenshots of the parameters and the preview.

Start at a chosen value. Setting startRange to 500 makes the first row 500, then 501, 502 and so on.

Jump and wait. With startRange 0, endRange 100 and jumpAmount 5 the values are 0, 5, 10, 15 and so on. Raising waitAmount to 3 makes each value repeat three times (0, 0, 0, 5, 5, 5) before the jump, the pattern for one parent value repeated across several child rows.

Count down through negatives. Set startRange -1, endRange -100 and sortOrder descending.

7.3.3 Other ways to get sequential values

RangeGen is the main tool, but the documentation shows several more sequential patterns.

• The domain id. When a domain is created or imported it automatically gets an id attribute that "generates a unique ID for each test data record" (Attributes Overview). For many tests that is the primary key and you need do nothing.
• RangeConstantGen. The string-generators list describes it as an increasing value "similar to the RangeGen" with an optional prefix and suffix. With range 1 to 5 and prefix test the output is test1 to test5. The StringRemoveGen page confirms the parameter names startRange and prefix for it. For ShopSphere, a prefix of ORD- and start 1001 gives ORD-1001, ORD-1002 and so on.
• ListGen in order. ListGen "generates items in a provided list in sequential or random order". Its random parameter defaults to False, so the list is walked in order. Its example sets waitAmount to 5 so each of Pending, Shipped and Delivered repeats for five rows before moving on (ListGen).
• PhoneNumberGen. The page says it "generates phone numbers in a sequence (100-1000, 100-1001, ..., 999-9999)", with two optional parameters: areaCode (the three-digit area code placed in front) and prefix (the starting prefix, from which the number increases). It points to RandomPhoneNumberGen for random numbers.

7.3.4 Continuing after existing data

Sometimes the target database already has rows, and new primary keys must start after the largest existing one. The help centre shows a linked-generator recipe (primary key values after the max value):

1. Add QueryOnceGen to the id attribute.

   It runs one query before generating. Set resourceName to the JDBC resource, query to select max(id) + 1 from <tableName> and give sampleValue (the page uses 5001) so the Preview pane has something to show.

   gen1 holds "the next free id".

2. Add RangeGen after it.

   For startRange, double-click the field and choose the Attribute Generator tab, then pick gen1 (it is written #{self.gen1}).

   New ids begin after the largest existing id, so inserts will not collide with existing rows.

RangeGen can reference QueryOnceGen only because QueryOnceGen sits to its left, a rule covered in section 7.6.

7.4 Random data and repeatable randomness

7.4.1 In plain words

Random data is data picked without a visible order. Random data is what makes a generated customer list look real: different names, ages and cities.

Random data has one practical problem. If a test fails today with a random customer, and tomorrow's run creates different customers, you cannot reproduce the failure. The fix is the seed: a starting number for the random picker. The same seed gives the same "random" sequence every time. Random but repeatable is the best of both.

7.4.2 RandomGen: a random number in a range

RandomGen "randomly generates a number within a range"; the page's own example is random ages between 18 and 65 (RandomGen).

The page's second example limits repeats: numbers 1 to 10, uniqueLimit 2, and a domain loop count of 15 so the possible values are not used up. Each number appears at most twice.

7.4.3 Random names, lists and strings

• NameGen. Generates first, last, male or female names (nameType), cased as capitalize, upperCase or lowerCase (caseType), in random, ascending or descending order (sortOrder), with an optional seed and a waitAmount. Its pool (1,000 male, 3,000 female and 10,000 last names) gives 40,000,000 combinations.
• ListGen. Set random to True to pick from a fixed list in random order (the page example picks one of five colours). Add unique True to use each list value only once; then the loop count must not exceed the number of values, or GenRocket throws an exception. ListGen supports up to 15 list items; for bigger lists the page recommends ListCSVV2Gen.
• RandomStringGen. Random text of a given length and stringType (letters, numbers, lettersAndNumbers, specialCharacters, ASCIICharacters or allCharacters), with caseType, seed, unique, include and exclude. The help page lists "test boundary conditions or invalid characters" and "filling a notes field with random strings to test character limits" among its uses. Its promo-code example links ConstantGen (PROMO), RandomStringGen (6 unique digits) and ConcatGen.

7.4.4 Seeding: random, but the same every time

The help page "What is Seeding?" defines seeding as generating "the same set of random data for the same value of a seed". It says a seed can be entered in several places in GenRocket, including the domain's Global Seed variable and the generator's own seed parameter (What is Seeding?). The page's example uses two attributes, number1 and number2, both RandomGen from 1 to 25:

• No seed on number1: a different set of numbers every time the data is generated.
• Seed 1 on number1: one fixed set, the same every run.
• Seed 1 on number2 too, same configuration: number2 gets the same set as number1, so use different seeds for columns that should look independent.
• Seed 2 on number2: a different fixed set.

The 2020 demo shows the problem live. With no seed, the first name, last name and middle initial change every time the preview refreshes. The CTO explains that a global seed, which can be assigned to many generators, makes the same random data appear every time for the same seed value. That matches the docs' domain Global Seed and generator seed.

7.5 Lists, weights and percentages

7.5.1 In plain words

Real data is lumpy. In a real shop, most orders are Delivered, a few are Pending and a handful are Cancelled. If your generator gives each status the same share, your test data is unrealistic, and reports built on it (percentage cancelled, say) look wrong. A weighted pattern says "give value A to 70 percent of the rows and value B to 30 percent".

There are two related ideas. A list is the set of allowed values (Pending, Shipped, Delivered). A weight says how often each list value should appear. Lists come first, weights shape them.

7.5.2 ListGen: the allowed values

ListGen "generates items in a provided list in sequential or random order" and is "a great choice when generating data from a fixed set of values (e.g., lookup table or categorical data)". Its documented parameters are list (one item per line), random (False by default), unique, waitAmount, iterate, seed, resetIndex and setLoop. It supports up to 15 items.

One parameter matters for the boundary lab at the end of this section. setLoop "gives users the ability to OVERRIDE the loop count at the Scenario Level and ONLY produce the number of rows defined in this list". If the first generator of an attribute is a ListGen with setLoop True, the scenario's loop count is locked to the list length and shows as "N" with no edit pencil. The help page "Why can't I update the Loop Count Value from the Scenario?" explains that this lock is the reason (link).

7.5.3 WeightGen: a two-way split

WeightGen "defines a percentage between 1 and 100 to determine how often values generated from variable1 will be selected over values generated from variable2". The parameters are percentage*, variable1*, variable2* and an optional seed. Variables can be constants or references to other generators or attributes (WeightGen).

The page's example: percentage 70, variable1 Pass, variable2 Fail gave 7 Pass and 3 Fail in ten rows. WeightGen splits between exactly two things; for more use MultiWeightGen.

7.5.4 MultiWeightGen: any number of weighted values

MultiWeightGen "allows multiple values to be weighted to determine how often each value is generated". The page's own example is rental vehicle types: economy 50 percent, midsize 35 percent, luxury 15 percent (MultiWeightGen).

With 100 records and exactPercentage True, the page says you get exactly 50 economy, 35 midsize and 15 luxury (one screenshot on that page shows exactPercentage False, so set it deliberately).

Note that MultiWeightGen "works in the totality of all rows and does not consider parent/child relations"; the overview names MultiWeightChildGen for that case.

For ShopSphere's status mix (Delivered 70, Shipped 15, Pending 10, Cancelled 5) use the same recipe with exactPercentage True and a seed; with 1,000 orders expect exactly 700, 150, 100 and 50.

How to give each parent a different number of children by weight is covered by the help page "How to generate Children based on Weights (Percentages)", and it is built in the parent and child lab.

7.6 Linked and conditional generators

7.6.1 In plain words

Sometimes a value depends on another value. A voting-age check depends on age. A "refund reason" only makes sense if the order is cancelled. In a spreadsheet you would write an IF formula. GenRocket has the same idea in two parts: linked generators (several generators chained in one attribute) and conditional logic generators (generators that choose one result by testing a condition).

7.6.2 Linked generators: the left-to-right rule

The "Linked Generators Overview" page gives the rules that every conditional recipe relies on (Linked Generators Overview):

• Linked generators run left to right (top to bottom in the table): the first generates first, the second next, and so on.
• A linked generator may only reference sibling generators to its left. Referencing one to the right "will yield null values" because it has not generated yet.
• The rightmost generator holds the value returned for the attribute. The earlier ones are workings that do not appear in the output.
• Each one gets a default name (gen1, gen2 and so on) and you can add an alias. In a parameter, a reference to a sibling looks like #{self.gen1}, as in the ConcatGen design-pattern page.

The same ordering applies between attributes: "Attributes can only reference other Attributes that are above them in the Attribute pane of a Domain." An attribute that references one below it "will return an empty value". The page "When can an Attribute not reference another Attribute?" shows the fix: click Rearrange Attributes and drag the attribute (link).

7.6.3 The conditional logic generators

The page "Conditional Logic Generators" groups them into calculation, condition-based and percentage-based generators (link). The table below keeps the descriptions short; check the generator's own page for parameters.

The overview adds that G-Rules can hold the same logic with conditions and actions, which suits complex multi-condition data. In the 2020 Q&A the CTO points to the same feature, "test data rules", for really complex if/then/else conditions, and to the linked case, switch and percentage generators for simpler ones.

7.6.4 EvalCaseGen: if age is 18 or more

EvalCaseGen takes an equation that uses var1 to var5, plus caseTrue and caseFalse. Allowed operators include &&, ||, !, >=, <=, ==, !=, <, >, % and /. Two cautions from the page: put string comparisons in double quotes (for example var1 == "Male"), and for numbers of type long append a lower-case L (var1l) (EvalCaseGen).

Its voting example is a perfect small boundary test. A domain Voting has an age attribute (RandomGen from 10 to 65) and an allowedToVote attribute using EvalCaseGen with equation var1 >= 18, var1 referencing the age attribute, caseTrue Yes and caseFalse No. Notice that the attribute order matters: age sits above allowedToVote.

7.6.5 EdgeCaseGen: sneak in the tricky value

EdgeCaseGen mixes a normal value with an edge-case value. It "generates edge case data useful for negative testing and testing edge cases". The page lists example edge cases: rounding issues in currency conversion, mismatched time zones, special characters in passwords, names longer than the character limit, names with invalid characters, uncommon file formats and validating a user's age (EdgeCaseGen).

So there are three ways to decide when the edge case appears: a true/false condition, a fixed cycle, or a percentage.

Example 1 from the page: a negative age every few rows. Three linked generators: RandomGen age (1 to 120), RangeGen negative (-120 up to -1) and EdgeCaseGen case with source the age, edgeCase the negative value and cycle 5.

Example 2: a first name longer than 10 characters, 25 percent of the time. Two ListGens hold short and long names, and EdgeCaseGen has percentage 25.

7.7 Null and blank values

7.7.1 In plain words

Imagine a paper form with a "middle name" box. There are three different situations. The person wrote a name (a value). The person wrote nothing and left the box empty (blank). Or the box was crossed out because the question did not apply (not applicable). Databases make the same distinction.

Applications treat these four differently, so test data needs all of them. GenRocket gives you three places to produce null and blank data.

7.7.2 Place 1: the attribute's own null settings

Every attribute has parameters on the Attribute Dashboard, above the generator. Four of them control nulls and visibility (Attribute Dashboard):

The docs give no worked example of % Null; set it, save and watch the Preview pane. It works for any generator because it sits on the attribute.

7.7.3 Place 2: generators that return null or blank

The help centre shows two generators for this purpose, in the walk-through "Flat/Nested JSON: Hide an Attribute when Value is NULL or Blank" (link):

• NullGen: "generates a NULL value". The screenshot shows a single parameter, nullType, set to NULL. Other nullType choices are not documented.
• ConstantGen: "generates a constant, non-changing value", and its value parameter accepts #{BLANK} to generate blank values and #{EMPTY} to generate an empty string (ConstantGen).

The string-generators list also names FillerGen, a repeating filler value; its parameters are not documented, so check the Preview pane.

7.7.4 Mixing normal, null and empty by percentage

The JSON walk-through combines both ideas in one attribute. A tester wants an address2 (apartment or suite) that is sometimes filled, sometimes null and sometimes empty. Four linked generators do it:

1. gen1 ListGen: Apt A, Apt B, Suite A, Suite B.
2. gen2 NullGen: a NULL value.
3. gen3 ConstantGen with #{EMPTY}: an empty value.
4. gen4 MultiWeightGen with valueList #{self.gen1}, #{self.gen2}, #{self.gen3} and percentList 60, 15, 25.

About 60 percent of rows get an apartment or suite, 15 percent NULL and 25 percent empty. Only the rightmost generator becomes the attribute's value.

Choosing an Output Condition on the attribute leaves a null or blank address2 out of the JSON for that record; the page's sample output omits the key on those rows. That matters for APIs that treat "missing key" and "null value" differently.

7.7.5 Place 3: how the receiver writes a null

A null is only a null inside GenRocket. The receiver decides how it is written to the file. The DelimitedFileReceiver documents a required parameter nullValue ("Represents a Null value") and a booleanValue format (DelimitedFileReceiver). The screenshot of its form shows nullValue pre-filled with (null). If a downstream loader expects the literal text NULL or an empty cell, change this parameter before you generate. A mismatch here is a classic source of "the data looks right in GenRocket but my load fails".

7.8 Boundary values and edge cases

7.8.1 Boundary value analysis, explained from zero

Suppose a form accepts an age from 18 to 65. You cannot test every possible number. Boundary value analysis (BVA) is a way to pick a handful of values that find most bugs. The idea comes from experience: programmers make "off by one" mistakes. They write age > 18 when they meant age >= 18. Such a bug is invisible when you test age 40 and obvious when you test age 18.

Here is the method in four steps.

1. Find the rule.

   Write down the allowed range. ShopSphere example: an order total is valid from 0.00 up to 999999.99.

2. Split the world into groups ("partitions").

   Everything below the range is invalid, everything inside is valid, everything above is invalid. Testing one value from inside each group covers "the typical case" of each.

3. Pick the values at each edge.

   For each boundary test the value just below it, on it and just above it.

4. Write the expected result for each value.

   Decide accept or reject for every value before generating anything, so the data file doubles as a test oracle.

For an inclusive range from a minimum to a maximum, the classic set is seven values: just below the minimum, the minimum, just above the minimum, one typical value, just below the maximum, the maximum, and just above the maximum.

An age rule works the same way. Say a ShopSphere customer must be 18 or older on a reference date of 2026-01-01.

7.8.2 How GenRocket produces boundary data

No boundary generator is documented. The documented building blocks combine into a few reliable recipes.

Why exact lists: a random generator might hit 999999.99 once in a million rows, or never; a boundary test must hit it every time.

7.8.3 Lab: a boundary-value suite for ShopSphere orders

7.9 Enforcing data type and size

7.9.1 In plain words

Every database column has a type and a size. A first_name VARCHAR(5) column holds at most five characters. An INT column holds whole numbers up to about two billion. If your generator produces "Maximiliano" for that first-name column, the insert fails, and a hundred rows of perfectly good data are lost because one name was too long.

For positive data, generated values must always fit the column, so loads never fail; GenRocket does this with a switch called Enforce Type/Limit. For negative data (the long-name edge case in section 7.6.5) you deliberately break the size.

7.9.2 Enforce Type/Limit

The page "How to Enforce Data Type and Size in Generated Data" explains the option (link):

• Value limits are enforced automatically when you import a DDL (database table definition) or an XTS file (GenRocket's extracted table schema). The option is switched on for every generator assigned during such an import.
• It is available on every generator and can be set on any individual generator in a domain.
• Use it "whenever you want the generated data to be within a defined data type and size".
• When on, it limits output to the Type and Size parameters of the attribute.

The page's example: NameGen with Enforce Type/Limit on, Type varchar and Size 5. First names in the Preview pane are limited to 5 characters.

These are boundary values in their own right: for a smallint column, 32767 is the maximum and 32768 is the "just above maximum" negative test.

7.9.3 Setting it by hand

For a manually built domain: open the attribute, type a data type (varchar, int, float, decimal) in Type and the limit in Size, click Save, then tick Enforce Type/Limit in the generator form and save the generator. The Preview pane then shows values within the size.

7.9.4 Decimal places and number formatting

Money needs fixed decimal places: 49.9 and 49.90 are different text, and a DECIMAL(8,2) column expects two.

NumberFormatGen formats a referenced number: pad with leading zeros, fix the number of decimal places, fix the number of digits, add commas, include a sign. Parameters (NumberFormatGen):

• reference*: the attribute (or linked generator) to format. It should produce a floating-point number.
• decimalFormat*: a pattern. The page's sample: 123456.789 with ###.## gives 123456.79.
• includeSign*, includeDecimal* and padLength*: whether a sign and the decimal point appear, and how many zeros to pad on the left.

The page links NumberFormatGen to RangeDecimalGen and RandomDecimalGen, which supply the decimal number. Those two have no separate pages; from the page's screenshots, RangeDecimalGen shows parameters startRange, endRange, decimalFormat, jumpAmount, waitAmount and sortOrder, and RandomDecimalGen shows startRange, endRange, decimalFormat and seed.

For the typical partition of total_amount use RandomDecimalGen from 1 to 5000 with a seed; by analogy with the screenshot's #0.0000, two decimals would be #0.00 (check in Preview). Boundary rows come from the boundary lab.

7.10 Dates and times

7.10.1 In plain words

Dates breed bugs: a birth date that makes someone 17 versus 18, an order dated 29 February, a timestamp at midnight, month-first versus day-first formats. Date test data needs three things: a format (how the date is written), a range (earliest and latest) and a pattern (sequential, random, or specific edge dates).

7.10.2 FlexibleDateRangeGen

GenRocket automatically picks FlexibleDateRangeGen for attributes whose imported data type is "date" or "time" (How are Generators Assigned). It generates dates from a start date, moving by a range and a jump (FlexibleDateRangeGen).

The page's first example: startDate 01-01-1970, startRange 0, endRange 4, initialJump 0, jumpAmount 10, nextBy Year, randomize false and randomizeMonthDay None. The first record is 01-01-1970 and the year grows by 10 each record: 1970, 1980, 1990, 2000, then the pattern restarts at 1970 on the fifth record.

7.10.3 Date formats

The "Date and Time format" page lists the pattern letters (link). The ones you will use most:

Year is y, month M, day d, hour H (0 to 23) or h (1 to 12), minute m, second s and am/pm a.

Capital M is month and lower-case m is minute, so yyyy-mm-dd prints the minute where you wanted the month. Attributes also have a Date Format parameter that "defines the Date Format if the Attribute is generating a Date".

7.10.4 DateDeltaGen: the gap between two dates

DateDeltaGen "computes the delta between two dates", in days, months, years or hours. Parameters: conversion*, formatOne*, formatTwo*, dateRefOne*, dateRefTwo*. The page's example links two FlexibleDateRangeGen generators and subtracts their dates (DateDeltaGen).

That gives a way to check an age rule in the data itself: generate a date_of_birth, hold a reference date in a ConstantGen (the ConstantGen page lists dates such as an effective date as a valid constant), and use DateDeltaGen with conversion years between them. The pages do not say how partial years are rounded, so verify the 17 and 18 rows by eye.

7.11 Pattern coverage table

Each row is a pattern, how GenRocket produces it, and the documented generator and parameters to reach for first.

7.12 Common mistakes and gotchas

7.13 Recap