Setting object values

Objects created from test data builders do not need to have any field values set. Every test data builder class provides default values for all required fields, and they create any related and required objects as needed.

For example, the following line of code creates a test user, even though no values have been provided for the test user:

var testUser = new UserContactBuilder()
    .create(bundleObj)

Specifying field values

You can specify values using methods within the test data builder class. These methods typically start with one of the following words:

  • withFieldName - These methods let you specify a value for a given field.
    • For example, addressBuilder.withCountry(Country.TC_FR)
  • asValue - These methods let you specify that the object has a given state. They can simplify code by not requiring you to specify the correct field or value to set the state.
    • For example, addressBuilder.asBusinessAddress()
  • onForeignKeyName - These methods let you specify a parent object that is the owner of the new object.
    • For example, policyBuilder.onAccount(testAccount)

When writing code that sets field values, the standard convention is to list each method on a separate, indented line that starts with the dot and method name. This makes it easier to use the code completion feature within Studio, improves the code's readability, and makes it easier to add additional lines.

The following code is an example of a test object that sets multiple field values and follows the standard convention for code format.

var testBusinessAddress = new AddressBuilder()
    .withAddressLine1("123 Main Street")
    .withCity("San Francisco")
    .withState(State.TC_CA)
    .withPostalCode("94110")
    .withCountry(Country.TC_US)
    .asBusinessAddress()
    .create(bundleObj)

Specifying unique values

Some fields require a field value that is unique before the object can be committed to the database. For example, person contacts have a TaxID field. This field must be a unique string value in the form XXX-XX-XXXX, where X is a digit 0 through 9 and - is a literal hyphen (such as "123-45-6789").

The gw.api.databuilder.UniqueKeyGenerator class can be used to generate unique values. It has its own sequence of integers and a get method. The get method has several child methods that return the next integer in the sequence in various formats. The get method never uses the same integer twice. So, within the context of testing, any two values generated from this method ought to be unique:

  • nextID - returns a 13-character alphanumeric string that consists of 6 random letters, a hyphen, and the next integer in the sequence as a 6-digit string with padded zeroes as needed.
  • nextInteger - returns the next integer in the sequence
  • nextKey - returns an 8-character alphanumeric string whose final characters are the next integer in the sequence

The following code is an example of executing each of these methods multiple times. Before this code was executed, the integers up through 36 have already been used.

uses gw.api.databuilder.UniqueKeyGenerator

print ("Next ID:  " + UniqueKeyGenerator.get().nextID())
print ("Next ID:  " + UniqueKeyGenerator.get().nextID())
print ("Next int: " + UniqueKeyGenerator.get().nextInteger())
print ("Next int: " + UniqueKeyGenerator.get().nextInteger())
print ("Next key: " + UniqueKeyGenerator.get().nextKey())
print ("Next key: " + UniqueKeyGenerator.get().nextKey())

OUTPUT:

Next ID:  QGJAJX-000037
Next ID:  FUGZFL-000038
Next int: 39
Next int: 40
Next key: WBFMHN41
Next key: MVJCVB42

The following code is an example of creating a user with a tax ID in the format XXX-XX-XXXX. The code appends the last four digits of the next ID to the string "000-00-". To do this, it uses the substring method, starting with the 9th character (where 0 is the first character and 9 is the first of the last four characters).

gw.transaction.Transaction.runWithNewBundle( \ bundleObj -> {
	var testUser = new UserContactBuilder()
	    .withFirstName("Tom")
	    .withLastName("Thompson")
	    .withTaxID("000-00-" + UniqueKeyGenerator.get().nextID().
			substring(9))
	    .create(bundleObj)
	print(testUser.FirstName)
	print(testUser.LastName)
	print(testUser.TaxID)
} , "su" )

OUTPUT:

Tom
Thompson
000-00-0043

Fields that cannot be set using methods

For every builder class, there may be fields whose values cannot be set using a withX, asX, or onX method. This includes:

  • Base configuration fields for which there is no related withX, asX, or onX method
  • Fields added through configuration

You can extend a base configuration test data builder to add methods to it so that a given field's value can be set. For more information, see Creating and extending test data builders.

Alternately, you can set the value after the object has been created. For example, suppose you extended the UserContact entity by adding a RemoteEmployee_Ext Boolean field. There is no method in the base configuration to set this field value. The following code shows an example of setting the field after the object has been created.

gw.transaction.Transaction.runWithNewBundle( \ bundleObj -> {
      var testUser = new UserContactBuilder()
	    .withFirstName("Tom")
	    .create(bundleObj)
	testUser.RemoteEmployee_Ext = true
} , "su" )