By using the DDT driver objects you can easily extract data stored in database tables that can be accessed via Microsoft ADO, from Excel sheets or files holding comma-separated values (CSV file). To obtain a driver object in your script, call one of the following methods of the DDT object:

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

Note: The DDT object is available only if the Data-Driven Testing plugin is installed in TestComplete. The plugin file name is tcDDTPlugin.pls, it is located in the <TestComplete>\Bin\Extensions folder.

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 or rows and columns. Each driver object contains 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, etc.

In case of the ADO DDT driver, the rows are rows of the table, to which the driver provides access and the columns are columns of this table. That is, the names and the order of columns coincide with the name and order of columns of the underlying database table.

In 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 information on specifics of using CSV files and retrieving data from them, see Using CSV Files as Data Storages.

In the Excel driver, the names and number of columns as well as the number of rows are determined by the populated cells in the underlying Excel sheet. Depending on certain Registry settings, the driver may recognize the first row of an Excel worksheet as column names or data. For information on this and on specifics of retrieving data from Excel sheets, see Using Excel Files as Data Storages.

Once you obtain a driver, you can iterate through the record of the driver table, retrieve them and use in your tests:

To walk through the records you can create a loop using the Next and EOF methods: 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.
To obtain the number and names of driver’s table, use the ColumnCount and ColumnName properties.

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;

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. This property holds a reference to the last created DDT driver. It is convenient to use since it frees you from using a global variable to hold the reference to the driver object.

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.

Note that 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

See Also