DUPLICATE_USERNAME Error During a Deployment and Using Change Set in Salesforce

Understanding Username Uniqueness in Salesforce

Salesforce usernames are unique across all orgs within the same environment type. For example, if a username a@b.c exists in any sandbox org, it cannot be used in another sandbox org. However, the same username can exist independently in a production org.

Uniqueness is enforced during deployments when tests are run, so an insert call will fail if the username is already registered in another org in the same environment.

Generating Unique Usernames to Avoid DUPLICATE_USERNAME Errors

To prevent duplicate usernames during Apex test execution, generate a globally unique username by combining multiple dynamic values: the Org ID (retrieved using UserInfo.getOrganizationId()), the current datetime as a string (with spaces, colons, and hyphens removed), and a random integer (generated using Math.random()). Concatenate these three values to create a unique string, then use that string as both the Username and Email fields of the test User record.

This approach guarantees uniqueness across sandbox instances because the combination of Org ID + timestamp + random number will never repeat across orgs or test runs.
Alternative approach: Set duplicate management rules in the org to prevent duplicate users from being created within the org's context. See Manage Duplicate Records for more information.

 

public static User createTestUser(Id roleId, Id profID, String fName, String lName) {
    String orgId = UserInfo.getOrganizationId();
    String dateString = String.valueof(Datetime.now()).replace(' ','').replace(':','').replace('-','');
    Integer randomInt = Integer.valueOf(math.rint(math.random()*1000000));
    String uniqueName = orgId + dateString + randomInt;
    User tuser = new User(  firstname = fName,
                            lastName = lName,
                            email = uniqueName + '@test' + orgId + '.org',
                            Username = uniqueName + '@test' + orgId + '.org',
                            EmailEncodingKey = 'ISO-8859-1',
                            Alias = uniqueName.substring(18, 23),
                            TimeZoneSidKey = 'America/Los_Angeles',
                            LocaleSidKey = 'en_US',
                            LanguageLocaleKey = 'en_US',
                            ProfileId = profId,
                            UserRoleId = roleId);
    return tuser;
}