In TestComplete tests, to extract data from external data sources, you can use DDT driver objects:

DDT.ADODriver - Creates a driver for a recordset, which can be accessed via Microsoft ADO DB.
DDT.CSVDriver - Creates a driver for a file holding values separated by commas.
DDT.ExcelDriver - Creates a driver for a sheet in an Excel document.

Requirements

The DDT object is available only if the Data-Driven Testing plugin is enabled in TestComplete.

This plugin is installed and enabled by default during the TestComplete installation. You can check the plugin status in the File > Install Extensions dialog in TestComplete. You can find the plugin in the Common group.

Working with drivers

To work with a driver in your tests, you can use the DDT.CurrentDriver property. This property holds a reference to the last created DDT driver. It is convenient to use because it frees you from using a global variable to hold the reference to the driver object.

Once you get a driver object, you can work with data, to which it provides access, in the same unified approach. The driver objects represent all data regardless of their storage format as a table of rows and columns:

For ADO DDT driver, the names and the order of columns coincide with the name and order of columns of the underlying database table.
For the CSV driver, each row corresponds to a line in the underlying CSV file and the column names are specified by the first line of this file.
For the Excel driver, the names and number of columns and rows are determined by the populated cells in the underlying Excel sheet. Depending on certain Windows Registry settings, the driver may recognize the first row of an Excel worksheet as column names or data.

Iterating through records

The driver objects have methods and properties that let you iterate through records of this table, obtain the numbers and names of columns, retrieve data stored in record fields:

To walk through the records, you can create a loop using the Next and EOF methods.

JavaScript, JScript

Python

VBScript

DelphiScript

C++Script, C#Script

JavaScript, JScript

var Driver = DDT.ExcelDriver("C:\\work\\UserData.xls", "Sheet1");

while (!Driver.EOF())
{
  …
  Driver.Next();
}

DDT.CloseDriver(Driver.Name);

Python

Driver = DDT.ExcelDriver("C:\\work\\UserData.xls", "Sheet1")

while not Driver.EOF():
  …
  Driver.Next()

DDT.CloseDriver(Driver.Name)

VBScript

Set Driver = DDT.ExcelDriver("C:\work\UserData.xls", "Sheet1")

While Not Driver.EOF()
  …
  Driver.Next()
WEnd

DDT.CloseDriver(Driver.Name)

DelphiScript

var Driver;
…
Driver := DDT.ExcelDriver('C:\work\UserData.xls', 'Sheet1');

while not Driver.EOF() do
begin
  …
  Driver.Next();
end;

DDT.CloseDriver(Driver.Name);

C++Script, C#Script

var Driver = DDT["ExcelDriver"]("C:\\work\\UserData.xls", "Sheet1");

while (!Driver["EOF"]())
{
  …
  Driver["Next"]();
}

DDT["CloseDriver"](Driver["Name"]);

Right after its creation the driver is on the first row of the driver’s table. To proceed to the next row, call Next. To determine the end of the table, call EOF. To return to the beginning of the data source, use the First method. Row-by-row backward navigation is not supported.
To obtain values stored in the current record of the driver’s table, use the Value property of the driver object. This property returns a column value by column index or column name.

JavaScript, JScript

Python

VBScript

DelphiScript

C++Script, C#Script

JavaScript, JScript

var value = DDT.CurrentDriver.Value("My Column");

Python

value = DDT.CurrentDriver.Value["My Column"]

VBScript

value = DDT.CurrentDriver.Value("My Column")

DelphiScript

var value;
…
value : = DDT.CurrentDriver.Value('My Column');

C++Script, C#Script

var value = DDT["CurrentDriver"]["Value"]("My Column");
To get the number and names of driver’s table, use the ColumnCount and ColumnName properties.

JavaScript, JScript

Python

VBScript

DelphiScript

C++Script, C#Script

JavaScript, JScript

var count = DDT.CurrentDriver.ColumnCount;
for (var i = 0; i < count; i++)
{
  var column = DDT.CurrentDriver.ColumnName(i);
  …
}

Python

count = DDT.CurrentDriver.ColumnCount
for i in range (0, count):
  column = DDT.CurrentDriver.ColumnName[i]
  …

VBScript

count = DDT.CurrentDriver.ColumnCount
For i = 0 To count - 1
  column = DDT.CurrentDriver.ColumnName(i)
  …
Next

DelphiScript

count := DDT.CurrentDriver.ColumnCount;
for i := 0 to count - 1 do
begin
  column := DDT.CurrentDriver.ColumnName[i];
  …
end;

C++Script, C#Script

var count = DDT["CurrentDriver"]["ColumnCount"];
for (var i = 0; i < count; i++)
{
  var column = DDT["CurrentDriver"]["ColumnName"](i);
  …
}

To evaluate the function whose name is specified in a cell of the driver’s table, you can either use the Eval function (in VBScript, JScript and Python) or the Evaluate function (in DelphiScript).

Note: If you use the Evaluate function to evaluate the routine that does not have a return value, it is necessary to specify the name of the unit that contains it before specifying the name of the evaluated procedure.

DelphiScript

// Both procedures are declared in the same unit, for example, Unit1
procedure PostMessage;
begin
Log.Message('Success');
end;

procedure TestEval;
begin
Evaluate('Unit1.PostMessage');
end;

Examples

The following code creates a DDT driver for an Excel sheet, runs through records of the driver’s table and posts values stored in record fields to the test log.

JavaScript, JScript

var RecNo;

// Posts data to the log (helper routine)
function ProcessData()
{
  var Fldr, i;

  Fldr = Log.CreateFolder("Record: " + aqConvert.VarToStr(RecNo));
  Log.PushLogFolder(Fldr);

  for(i = 0; i < DDT.CurrentDriver.ColumnCount; i++)
    Log.Message(DDT.CurrentDriver.ColumnName(i) + ": " + aqConvert.VarToStr(DDT.CurrentDriver.Value(i)));

  Log.PopLogFolder();
  RecNo = RecNo + 1;
}

// Creates the driver (main routine)
function TestDriver()
{
  var Driver;

  // Creates the driver
  // If you connect to an Excel 2007 sheet, use the following method call:
  // Driver = DDT.ExcelDriver("C:\\MyFile.xlsx", "Sheet1", true);
  Driver = DDT.ExcelDriver("C:\\MyFile.xls", "Sheet1");

  // Iterates through records
  RecNo = 0;
  while (! Driver.EOF() )
  {
    ProcessData(); // Processes data
    Driver.Next(); // Goes to the next record
  }

  // Closes the driver
  DDT.CloseDriver(Driver.Name);
}

Python

RecNo = 0

# Posts data to the log (helper routine)
def ProcessData():
  global RecNo
  Fldr = Log.CreateFolder("Record: " + aqConvert.VarToStr(RecNo))
  Log.PushLogFolder(Fldr)

  for i in range(DDT.CurrentDriver.ColumnCount):
    Log.Message(DDT.CurrentDriver.ColumnName[i] + ": " + aqConvert.VarToStr(DDT.CurrentDriver.Value[i]))

  Log.PopLogFolder()
  RecNo = RecNo + 1

# Creates the driver (main routine)
def TestDriver():

  # Creates the driver
  # If you connect to an Excel 2007 sheet, use the following method call:
  # Driver = DDT.ExcelDriver("C:\\MyFile.xlsx", "Sheet1", True)
  Driver = DDT.ExcelDriver("C:\\MyFile.xls", "Sheet1")

  # Iterates through records
  while not Driver.EOF():
    ProcessData(); # Processes data
    Driver.Next(); # Goes to the next record

  # Closes the driver
  DDT.CloseDriver(Driver.Name);

VBScript

Dim RecNo

' Posts data to the log (helper routine)
Sub ProcessData
  Dim Fldr, i

  Fldr = Log.CreateFolder("Record: " + aqConvert.VarToStr(RecNo))
  Log.PushLogFolder Fldr

  For i = 0 To DDT.CurrentDriver.ColumnCount - 1
    Log.Message DDT.CurrentDriver.ColumnName(i) + ": " + aqConvert.VarToStr(DDT.CurrentDriver.Value(i))
  Next

  Log.PopLogFolder
  RecNo = RecNo + 1
End Sub

' Creates the driver (main routine)
Sub TestDriver
  Dim Driver

  ' Creates the driver
  ' If you connect to an Excel 2007 sheet, use the following method call:
  ' Set Driver = DDT.ExcelDriver("C:\MyFile.xlsx", "Sheet1", True)
  Set Driver = DDT.ExcelDriver("C:\MyFile.xls", "Sheet1")

  ' Iterates through records
  RecNo = 0
  While Not Driver.EOF()
    Call ProcessData() ' Processes data
    Call Driver.Next() ' Goes to the next record
  WEnd

  ' Closes the driver
  Call DDT.CloseDriver(Driver.Name)
End Sub

DelphiScript

var RecNo;


// Posts data to the log (helper routine)
procedure ProcessData;
var
  Fldr, i : OleVariant;
begin
  Fldr := Log.CreateFolder('Record: ' + aqConvert.VarToStr(RecNo));
  Log.PushLogFolder(Fldr);

  for i := 0 to DDT.CurrentDriver.ColumnCount - 1 do
    Log.Message(DDT.CurrentDriver.ColumnName[i] + ': ' + aqConvert.VarToStr(DDT.CurrentDriver.Value[i]));

  Log.PopLogFolder;
  RecNo := RecNo + 1;
end;

  // Creates the driver (main routine)
procedure TestDriver;
var
  Driver : OleVariant;
begin
  // Creates the driver
  // If you connect to an Excel 2007 sheet, use the following method call:
  // Driver := DDT.ExcelDriver('C:\MyFile.xlsx', 'Sheet1', true);
  Driver := DDT.ExcelDriver('C:\MyFile.xls', 'Sheet1');

  // Iterates through records
  RecNo := 0;
  while not Driver.EOF() do
  begin
    ProcessData; // Processes data
    Driver.Next; // Goes to the next record
  end;

  // Closes the driver
  DDT.CloseDriver(Driver.Name);
end;

C++Script, C#Script

var RecNo;

// Posts data to the log (helper routine)
function ProcessData()
{
  var Fldr, i;

  Fldr = Log["CreateFolder"]("Record: " + aqConvert.VarToStr(RecNo));
  Log["PushLogFolder"](Fldr);

  for(i = 0; i < DDT["CurrentDriver"]["ColumnCount"]; i++)
    Log.Message(DDT["CurrentDriver"]["ColumnName"](i) + ": " + aqConvert.VarToStr(DDT["CurrentDriver"]["Value"](i)));

  Log["PopLogFolder"]();
  RecNo = RecNo + 1;
}

// Creates the driver (main routine)
function TestDriver()
{
  var Driver;

  // Creates the driver
  // If you connect to an Excel 2007 sheet, use the following method call:
  // Driver = DDT["ExcelDriver"]("C:\\MyFile.xlsx", "Sheet1", true);
  Driver = DDT["ExcelDriver"]("C:\\MyFile.xls", "Sheet1");

  // Iterates through records
  RecNo = 0;
  while (! Driver["EOF"]() )
  {
    ProcessData(); // Processes data
    Driver["Next"](); // Goes to the next record
  }

  // Closes the driver
  DDT["CloseDriver"](Driver["Name"]);
}

As you can see, to address the driver within the ProcessData routine, we used the DDT.CurrentDriver property.

In the example above we iterate through the records of the driver’s table using the Next and EOF methods. The driver object contains the DriveMethod("UnitName.RoutineName") function that let you automate the iteration. DriveMethod runs through all the records of the driver’s table and execute the routine passed to it as a parameter.

JavaScript, JScript

var RecNo;

// Posts data to the log (helper routine)
function ProcessData()
{
  var Fldr, i;

  Fldr = Log.CreateFolder("Record: " + aqConvert.VarToStr(RecNo));
  Log.PushLogFolder(Fldr);

  for(i = 0; i < DDT.CurrentDriver.ColumnCount; i++)
    Log.Message(DDT.CurrentDriver.ColumnName(i) + ": " + aqConvert.VarToStr(DDT.CurrentDriver.Value(i)));

  Log.PopLogFolder();
  RecNo = RecNo + 1;
}

// Creates the driver (main routine)
function TestDriver()
{
  var Driver;

  // Creates the driver
  // If you connect to an Excel 2007 sheet, use the following method call:
  // Driver = DDT.ExcelDriver("C:\\MyFile.xlsx", "Sheet1", true);
  Driver = DDT.ExcelDriver("C:\\MyFile.xls", "Sheet1");

  // Iterates through records
  RecNo = 0;
  Driver.DriveMethod("Unit1.ProcessData")

  // Closes the driver
  DDT.CloseDriver(Driver.Name);
}

Python

RecNo = 0

#Posts data to the log (helper routine)
def ProcessData():
  global RecNo
  Fldr = Log.CreateFolder("Record: " + aqConvert.VarToStr(RecNo))
  Log.PushLogFolder(Fldr)

  for i in range(DDT.CurrentDriver.ColumnCount):
    Log.Message(DDT.CurrentDriver.ColumnName[i] + ": " + aqConvert.VarToStr(DDT.CurrentDriver.Value[i]))

  Log.PopLogFolder()
  RecNo = RecNo + 1


# Creates the driver (main routine)
def TestDriver():
  # Creates the driver
  # If you connect to an Excel 2007 sheet, use the following method call:
  # Driver = DDT.ExcelDriver("C:\\MyFile.xlsx", "Sheet1", True);
  Driver = DDT.ExcelDriver("C:\\Users\\Public\\Documents\\TestComplete 11 Samples\\Common\\Data-Driven Testing\\TestBook.xlsx", "TestSheet", True)

  # Iterates through records
  RecNo = 0
  Driver.DriveMethod("Unit1.ProcessData")

  # Closes the driver
  DDT.CloseDriver(Driver.Name)

VBScript

Dim RecNo

' Posts data to the log (helper routine)
Sub ProcessData
  Dim Fldr, i

  Fldr = Log.CreateFolder("Record: " + aqConvert.VarToStr(RecNo))
  Log.PushLogFolder Fldr

  For i = 0 To DDT.CurrentDriver.ColumnCount - 1
    Log.Message DDT.CurrentDriver.ColumnName(i) + ": " + aqConvert.VarToStr(DDT.CurrentDriver.Value(i))
  Next

  Log.PopLogFolder
  RecNo = RecNo + 1
End Sub

' Creates the driver (main routine)
Sub TestDriver
  Dim Driver

  ' Creates the driver
  ' If you connect to an Excel 2007 sheet, use the following method call:
  ' Set Driver = DDT.ExcelDriver("C:\MyFile.xlsx", "Sheet1", True)
  Set Driver = DDT.ExcelDriver("C:\MyFile.xls", "Sheet1")

  ' Iterates through records
  RecNo = 0
  Driver.DriveMethod "Unit1.ProcessData"

  ' Closes the driver
  Call DDT.CloseDriver(Driver.Name)
End Sub

DelphiScript

var RecNo;


// Posts data to the log (helper routine)
procedure ProcessData;
var
  Fldr, i : OleVariant;
begin
  Fldr := Log.CreateFolder('Record: ' + aqConvert.VarToStr(RecNo));
  Log.PushLogFolder(Fldr);

  for i := 0 to DDT.CurrentDriver.ColumnCount - 1 do
    Log.Message(DDT.CurrentDriver.ColumnName[i] + ': ' + aqConvert.VarToStr(DDT.CurrentDriver.Value[i]));

  Log.PopLogFolder;
  RecNo := RecNo + 1;
end;

  // Creates the driver (main routine)
procedure TestDriver;
var
  Driver : OleVariant;
begin
  // Creates the driver
  // If you connect to an Excel 2007 sheet, use the following method call:
  // Driver := DDT.ExcelDriver('C:\MyFile.xlsx', 'Sheet1', True);
  Driver := DDT.ExcelDriver('C:\MyFile.xls', 'Sheet1');

  // Iterates through records
  RecNo := 0;
  Driver.DriveMethod('Unit1.ProcessData');

  // Closes the driver
  DDT.CloseDriver(Driver.Name);
end;

C++Script, C#Script

var RecNo;

// Posts data to the log (helper routine)
function ProcessData()
{
  var Fldr, i;

  Fldr = Log["CreateFolder"]("Record: " + aqConvert.VarToStr(RecNo));
  Log["PushLogFolder"](Fldr);

  for(i = 0; i < DDT["CurrentDriver"]["ColumnCount"]; i++)
    Log.Message(DDT["CurrentDriver"]["ColumnName"](i) + ": " + aqConvert.VarToStr(DDT["CurrentDriver"]["Value"](i)));

  Log["PopLogFolder"]();
  RecNo = RecNo + 1;
}

// Creates the driver (main routine)
function TestDriver()
{
  var Driver;

  // Creates the driver
  // If you connect to an Excel 2007 sheet, use the following method call:
  // Driver = DDT["ExcelDriver"]("C:\\MyFile.xlsx", "Sheet1", true);
  Driver = DDT["ExcelDriver"]("C:\\MyFile.xls", "Sheet1");

  // Iterates through records
  RecNo = 0;
  Driver["DriveMethod"]("Unit1.ProcessData");

  // Closes the driver
  DDT["CloseDriver"](Driver["Name"]);
}

DriveMethod simplifies the processing, but Next and EOF give you more “freedom”: you can exclude certain data from processing either within TestDriver, or within ProcessData routine. With DriveMethod you can exclude data from processing only within the ProcessData function.

If you need to use several drivers simultaneously, you can assign a name to each driver and then use the DDT.DriverByName property to obtain the desired driver by its name. This property allows you to avoid using a global variable to store references to the desired driver object. This is especially useful, if you create and use drivers in several units:

JavaScript, JScript

[Unit1.sj]
var drv = DDT.ExcelDriver("C:\\MyFiles\\MyFile.xls", "Sheet1");
drv.Name = "My Driver";
...
[Unit2.sj]
var drv2 = DDT.DriverByName("My Driver");
...

Python

[Unit1.py]
drv = DDT.ExcelDriver("C:\\MyFiles\\MyFile.xls", "Sheet1");
drv.Name = "My Driver";
...
[Unit2.py]
drv2 = DDT.DriverByName("My Driver");
...

VBScript

[Unit1.svb]
Set drv = DDT.ExcelDriver("C:\MyFiles\MyFile.xls", "Sheet1")
drv.Name = "My Driver"
...
[Unit2.svb]
Set drv2 = DDT.DriverByName("My Driver")
...

DelphiScript

[Unit1.sd]
var
drv : OleVariant;
begin
drv := DDT.ExcelDriver('C:\MyFiles\MyFile.xls', 'Sheet1');
drv.Name := 'My Driver';
...
end;
...
[Unit2.sd]
var
drv2 : OleVariant;
begin
drv2 := DDT.DriverByName('My Driver');
...
end;
...

C++Script, C#Script

[Unit1.scs]
var drv = DDT["ExcelDriver"]("C:\\MyFiles\\MyFile.xls", "Sheet1");
drv["Name"] = "My Driver";
...
[Unit2.scs]
var drv2 = DDT["DriverByName"]("My Driver");
...

To address the driver that was created last, you can also use the DDT.CurrentDriver property.

Using DDT Drivers

Requirements

Working with drivers

Iterating through records

Examples

See Also