The Scripting Object at a Glance
DTM Test Automation:
Using the Device Selection Scripting Object(DSSO)
March 29, 2007
Abstract
This paper provides information about the Device Selection Scripting Object (DSSO) that is provided with the Driver Test Manager (DTM). It provides guidelines for users of the DTM to help them automate their driver testing processes.
This information applies for the following operating systems:
Microsoft Windows Server®2008
Windows Vista®
Microsoft Windows Server 2003
Microsoft Windows XP
1
The Scripting Object at a Glance
Disclaimer
This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.
© 2007 Microsoft Corporation. All rights reserved.
Microsoft, Windows, Windows NT, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
1
The Scripting Object at a Glance
Contents
Introduction
Part 1
The Scripting Object at a Glance
Getting Started with Automation
Device Selection and Testing with DTM Studio UI
Device Selection and Testing with C# Automation Program
Setting up the Build Environment
Adding References to the Required DLLs
Developing the Automation Program in C#
Part 2
ICategory Interface
The Properties of the ICategory Interface
The Methods of the ICategory Interface
IDescriptor Interface
The Properties of the IDescriptor Interface
IDevice Interface
The Properties of the IDevice Interface
The Methods of the IDevice Interface
IDeviceScript Interface
The Methods of the IDeviceScript Interface
IDeviceScriptExtension Interface
The Methods of the IDeviceScriptExtension Interface
IDriver Interface
The Properties of the IDriver Interface
The Methods of the IDriver Interface
IJob Interface
The Properties of the IJob Interface
The Methods of the IJob Interface
IParameter Interface
The Properties of the IParameter Interface
IResource Interface
The Properties of the IResource Interface
The Methods of the IResource Interface
IResourcePool Interface
The Properties of the IResourcePool Interface
The Methods of the IResourcePool interface
IResult Interface
The Properties of the IResult Interface
IResultSummary Interface
The Properties of the IResultSummary Interface
The Method of the IResultSummary Interface
ISchedule Interface
The Methods of the ISchedule Interface
IScheduleItem Interface
The Properties of the IScheduleItem interface
The Methods of the IScheduleItem interface
1
DTM Test Automation
Introduction
Note: This documentation is preliminary and is subject to change.
The Device Selection Scripting Object (DSSO) is designed so that users can write a script or a program that automates the selection of a device, the scheduling of jobs to be run against the device, and the running of the associated jobs. The DSSO is a managed object (written in Microsoft Visual C#) so that it can interface with the Windows Testing Technologies object model.
The following diagram (Figure 1) shows the interaction of the user interface and the scripting object with DTM and the user.
Figure 1: Device scripting object interaction
To reiterate, withthe scripting ability provided by the DSSO, users can select existing devices along with the jobs to be scheduled.
Note:It is not the goal of this document to teach you how to change or edit any DTM objects.
The remainder of this document discusses the following topics divided into two parts:
PART I
- A general overview that shows the scripting object at a glance.
- A walk-through of the necessary steps to use the Device Selection UI to manually select a given device, schedule jobs to be run against it, and then run those jobs.
- Step-by-step instructions to automate the selection and testing of the same device that was selected and tested using the Device Selection UI.
PART II
- Brief introductions of the interfaces that make up the DSSO, with an emphasis on the properties and methods exposed for use.
Note: Although there is a long-term goal for the DSSO to also expose all of its public interfaces through COM for compatibility with non-C# scripts, at the time of this writing, the COM feature of the DSSO has not been implemented.
1
DTM Test Automation
Part 1
The Scripting Object at a Glance
The following tablesummarizes the interfaces and the corresponding properties or methods within the DSSO.
Interface Name / Properties and/or MethodsICategory / Id
FullPath
Name / *GetJobs
*GetSubCategories
IDescriptor / Id
FullPath
Name / ParentId
ParentName
IDevice / ClassName
Description
DeviceXML
FriendlyName
InstanceID / Resource
*GetAttribute
*GetParameterOverride
*HasAttribute
*HasParameterOverride
IDeviceScript / *Close
*ConnectToDataStore
*ConnectToDefaultDataStore
*ConnectToNamedDataStore
*CreateDriverSubmission
*CreateHardwareSubmission
*CreateNewSchedule
*CreateNewScheduleItem
*CreateNewSubmissionDeviceData
*CreateSubmissionCabinet
*CreateSystemSubmission
*DeleteSubmission
*GetConnectString
*GetCurrentDataStore
*GetCurrentExtensionDataAssemblies
*GetDataStores
*GetDescriptorByName
*GetDescriptorByPath
*GetDevices
*GetDevicesByClass
*GetDevicesFromInf
*GetDevicesFromPool / *GetDriversFromInf
*GetDriversFromPool
*GetExtensionUI
*GetJoByName
*GetJobCategories
*GetJobCategoriesByClass
*GetJobCategoriesByDevice
*GetJobCategoryByName
*GetJobsByDescriptor
*GetJobsByDescriptorObject
*GetJobsFromCategory
*GetLogoDescriptors
*GetResourcePoolById
*GetResourcePoolByName
*GetResourcePoolCollection
*GetResources
*GetScheduleExtension
*GetScheduleXml
*GetSubmissionById
*GetSubmissionByName
*GetSubmissions
*RunSchedule
IDeviceScriptExtension / *GetExtensionUI
*ProcessSchedule / *SetExtensionData
IDriver / ClassName
DriverXml
FriendlyName
Id
Location
Submission
SubmissionId
Version / *GetChangedFiles
*GetDevices
*GetFiles
*GetHardwareIds
*GetMatchingHashDevices
*GetServices
*IsDriverValid
IJob / Id
Guid
Name
*GetCategories
*GetJobDescriptorById / *GetJobDescriptorByName
*GetJobDescriptors
*GetParameterByName
*GetParameters
*GetResults
IParameter / Name
ScheduleDisplay / ScheduleValue
Value
IResource / Id
Location
Name
OperatingSystem
ProcessorArchitectureResourcePool / *GetDevices
*GetDevicesByClass
*GetDevicesByHardwareId
*GetDimension
*GetDrivers
*SetDimension
IResourcePool / FullPath
ParentResourcePoolId
ResourcePoolId
ResourcePoolName
*GetDevices
*GetDevicesByClass / *GetDevicesByHardwareId
*GetDrivers
*GetResourceById
*GetResourceByName
*GetResources
*HasDimensionApplied
IResult / CurrentPipeline
CurrentPipelineId
CurrentPipelineState
Fail
Id
Job / JobId
NotApplicable
NotRun
Pass
ResultStatus
Total
IResultSummary / CanceledResults
CompletedResults
Id
InProgressResults
InvestigateResults / Name
ResolvedResults
ResultSummaryStatus
TotalResults
*GetResults
ISchedule / *AddDeviceJob
*AddDriverJob
*AddJob
*AddScheduleItem / *AddSubmission
*AddResultSummary
*SetResourcePool
IScheduleItem / Context
Device
Driver
Extension
FriendlyName / Job
JobName
ResourceString
*AddResource
*GetResources
ISubmission / HardwareId
Id
Name
OperatingSystem
ProcessorArchitecture
ResourcePool
ResourcePoolId
ResourcePoolName
ResultSummary
ResultSummaryId
SystemId
*AddDriver
*GetDeviceData / *GetDevices
*GetDrivers
*GetFailingResults
*GetJobs
*GetLogoDescriptors
*GetNotRunJobs
*GetResults
*GetTotalResults
*ProcessJobs
*RunStatusExtensions
*SetDeviceData
*SetLogoDescriptors
ISubmissionDeviceData / Data
Name / Submission
SubmissionId
ISubmissionScheduleExtension / MaxProgress
*ProcessSchedule / *StepProgress
Note:The asterisk (*) means that this is a method of the interface.
1
DTM Test Automation
Getting Started with Automation
After you have installed the DTM Controller and client(s), and after the relevant MCU Policies have been successfully applied,you can use DTM Studio to manually select a device for testing or you can automate this process. The MCU policy needed for this exercise is the WDK\ConfigureKeyboard policy. In the next section, you will manually select and test a given device that is attached to a specific computer within a machine pool. Next, you will complete a procedure in which you automate the testing of the same device. To keep this tutorial simple, the chosen device is a standard 101-key keyboard that uses drivers provided with Windows.
Note: The following two sections provide a general introduction to test automation. This information is not intended to be a comprehensive treatment of the driver testing features of the DTM.
Device Selection and Testing with DTM Studio UI
The following procedure shows you how to test a standard 101-key keyboard. To successfully perform these steps you must have DTM Controller, Studio, and client already installed.
- Open DTM Studio and switch to the Job Monitor window.
You can also open a new Job Monitor window by clicking Explorers, and then clicking Job Monitor.
- In the Machine Pool pane, click Default Pool, and then locate the client computer in the Machines pane.
- Create a new machine pool.
a)In the Machine Pool pane, right-click the root pool (indicated by the '$' symbol), and then click Add Machine Pool.
b)Type the name Test Pool, click Apply, and then click OK.
Your new machine pool, Test Pool, now appears in the Machine Pool console tree.
- Move the client computer to the new machine pool.
- Change the status of the client computer to the Resetstate.
- Apply the required MCU Policy to the machine pool.
a)Right-click the Test Pool machine pool, and click Properties.
b)On the MCU Policy tab,select WDK\ConfigureKeyboard from the Available Dimensions list box.
c)Click Add, and then click OK.
- Select a logo program.
a)Click Explorers, and then select Device Console.
b)When Device Console finishes loading, confirm that Test Pool is selected in the Machine Pool drop-down list box, and then click Submission to switch to submission mode.
c)From the Submission drop-down list box, select <New Submission>.
d)In the Create New Submission dialog box, select your operating system, and then click Next.
e)Click Device Submission, and then click Next.
f)Click Input > Keyboard, and then click Next.
If you are using a portable computer, click Display > Monitors > LCD, and then click Next.
g)Select a submission level (Basic or Premium), and then click Next.
h)Provide a name for your submission: Type Keyboard submission.
i)In the Machine Pool pane, click Test Pool, and then click Next.
Note You select Test Pool because it contains the client computer.
- Select a driver for the keyboard.
a)Select the No INF file check box, and then click Next.
b)Expand the Test Pool node, and then expand Keyboards to select the device to be tested.
c)Select the check box next to your keyboard, and then click Next.
d)If you see the message "ERROR: No Submission Drivers specified," click OK.
e)In the summary that shows the submission name, machine pool name and your keyboard's identifier, click Finish.
- Select and schedule the job you are going to run.
a)In the Available Jobs pane in the Device Console window expand the Driver Reliability node.
b)Select the check box for the Prefast for Drivers Test job.
c)At the bottom-left of the Device Console window, click Add Selected.
d)Click Schedule Jobs.
Note You can switch to the Job Monitor window, wait about 5 seconds, and then click Refresh or press F5. The Job Execution Status pane displays the job that is currently running. After a few moments, your monitor should start responding to the scheduled job.
Device Selection and Testing with C# Automation Program
This section shows you how to develop an automation program (using Microsoft Visual C#) that will repeat the test from the previous section.
The C# program that is used to automate the keyboard test is presented as a logical series of code snippets. Error checking has been removed from code snippets for purposes of clarity.
Note:The full-length program is provided for educational purposes only. If you use the sample C# program for testing in a production environment, you do so at your own risk.
Setting up the Build Environment
If you want to run your executable with the debugger, follow these steps to configure the relevant Visual Studio environment variables.
To set up the build environment
1. On the main menu, click Project, and thenclick Project Properties.
2. On the left side navigation pane, click Debug.
3. In the Start Action area, click Start external program.
4. Type C:\Program Files\Microsoft Driver Test Manager\Studio\<prog_name.exe
where <program name.exe> is the name of your automation program.
5. In the left pane,clickBuild Events.
6. In the text box titled Post-build event command line, type the following:
Copy "$(TargetPath)" "C:\Program Files\Microsoft Driver Test Manager\Studio\$(TargetFileName)"
7. Close the dialog box. Your changes will automatically be saved.
Adding References to the Required DLLs
To get a new C# automation program to compile correctly, certain references must be set. Assuming DTM Studio has been installed on your development computer,complete the following procedure to make sure these references are set.
To add references to the required DLLs
1. Right-click your solution in the Solution Explorer, and then click Add References.
2. On the Browse tab, navigate to c:\Program Files\Microsoft Driver Test Manager\Studiolocation.
4. Select all of the following DLLs
DeviceScript.dll
InfReader.dll
JobVerification.dll
Microsoft.DistributedAutomation.Packager.WDKSubmissionCab.dll
Microsoft.WTT.Diagnostics.dll
NonXmlDataReader.dll
WTTOMAsset.dll
WTTOMBase.dll
WTTOMDeviceKit.dll
WTTOMDimension.dll
WTTOMFeature.dll
WTTOMIdentity.dll
WTTOMJObs.dll
WTTOMParameter.dll
WTTOMResource.dll
WTTOMSQLProvider.dll
5. Click OK.
The new list of referenced DLLs will also include the following three, which were pre-selected aspart of the installation of Visual Studio.
System.dll
System.Data.dll
System.Xml.dll
Developing the Automation Program in C#
To develop the automation program in C#
1. Create an instance of the DeviceScript object, and then use the ConnectToNamedDatastoremethod of this object to connect to the datastore of the DTM Controller. The name of the controller is assumed to be dtm-controller.
//Create an instance of the DeviceScript object
DeviceScript script = new DeviceScript( );
//Now connect to a named datastore. Remember to replace the name dtm-controller
//with the name of your DTM controller
script.ConnectToNamedDatastore("dtm-controller");
2. Select the resource pool that includes the computerthat has the keyboard to be tested. Theexample machine pool name is test-pool.
//Create an instance of the ResourcePool object and initialize it
IResourcePool pool = script.GetResourcePoolByName("test-pool");
3. Scan the machine pool and retrieve all devices that fall into the same class as the one to be tested. In this case, this is the keyboard class.
//Create array of objects and initialize with devices in the specified class
Object[ ] keyboardDevices = pool.GetDevicesByClass("KEYBOARD");
4. Create an instance of the device class and initialize it with the first member of the object array that you created earlier. You must cast the variable type from Object to IDevice.
//To select single keyboard, create Device object and initialize it with keyboardDevices[0]
IDevice device = keyboardDevices[0] as IDevice;
5. Select one job to be run against the keyboard device that you selected earlier. Then use this job to initialize an instance of the Job object. You must cast the variable type from Object to IJob. To duplicatethe manual steps presented earlier, the Prefast for Drivers Test job is chosen again.
//First create an array of available keyboard jobs
Object[ ] keyboardJobs = script.GetJobByName("Prefast for Drivers Test");
//Create an instance of the Job object to store the selected job.
IJob job = keyboardJobs[0] as IJob;
6. Create a Schedule object that will be used to schedule and run the job you choose.
//Create instance of ISchedule object, and then add the selected job to the ISchedule object
ISchedule schedule = script.CreateNewSchedule( );
schedule.AddDeviceJob(device, job);
7. Indicate the resource pool that the schedule will be run against, and then run the schedule.
//Select target resource pool for the schedule, and then run the schedule
Schedule.SetResourcePool(pool);
Script.RunSchedule(schedule);
The Complete Listing of the C# Automation Program
The complete sample program is shown below, with error checking omitted for simplicity and clarity.
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.DistributedAutomation.DeviceSelection;
namespace automate0
{
class AutoJob
{
static void Main(string[] args)
{
DeviceScript script = new DeviceScript();
try
{
script.ConnectToNamedDataStore("p2201-lab");
}
catch(Exception e)
{
Console.WriteLine("Error: " + e.Message);
}
IResourcePool pool = script.GetResourcePoolByName("Test Pool");
Console.WriteLine("Selected pool: " + pool.ResourcePoolName);
Object[] keyboardDevices = pool.GetDevicesByClass("KEYBOARD");
IDevice device = keyboardDevices[0] as IDevice;
Console.WriteLine("Device: " + device.FriendlyName);
Object[] keyboardJobs = script.GetJobByName("Prefast for Drivers Test");
IJob job = keyboardJobs[0] as IJob;