Creating a customized Manual Test template for Visual Studio 2005
Update (01/12/2008): The post has been updated to show the differences with respect to Visual Studio 2008. The corresponding notes have been written in blue.
Part of the work we do at InCycle Software is help our customers install and configure Visual Studio Team System (VSTS). This includes the customization of work items, reports, process guidance, etc. For some customers, we even help them customize some of the templates.
Visual Studio 2005 Team Suite and Visual Studio 2005 Team Edition for Software Testers have templates specific to testing. One of these test templates is the Manual Test. There are two Manual Test formats: Text and Word. The steps to follow will show you one way to customize the look and structure of the Word format document and package it to create your own template.
I will assume that you are somewhat familiar with the Visual Studio environment and that you already know how to create Solutions and Projects. For these and other walkthroughs please refer to the Samples and Walkthroughs pages in MSDN.
The testing templates in Visual Studio 2005 are nothing more than extensions to the environment. In order to create a complete extension you would need to use the Visual Studio SDK. Creating a full Visual Studio extension is beyond the scope of this post.
With the help from Sarah Cameron, one of my colleagues at work, we have polished and divided the process into three main steps.
Create the Template
1. Start with the existing Manual Test template that can be found in your Visual Studio's Item Template folder. In my installation the path is D:\Program Files\Microsoft Visual Studio 8\Common7\IDE\ItemTemplates\CSharp\1033. The template file name is ManualTestWordFormat.zip.
Note: In Visual Studio 2008 the above path would be D:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates\CSharp\1033. The template file name is the same. The path varies from Microsoft Visual Studio 8 to Microsoft Visual Studio 9.0.
2. Create a folder that will contain your customized template files. In this example, I will call the folder InCycleManualTest. This will serve as a staging area and is really optional.
3. Extract the contents of the ManualTestWordFormat.zip into the InCycleManualTest folder. The folder should now contain two files: ManualTest.mht and ManualTest.vstemplate.
4. Rename both extracted files to match the name of your template folder. In this example, the files are renamed to InCycleManualTest.mht and InCycleManualTest.vstemplate, respectively.
5. Open the .mht file in Microsoft Word and modify the document to suit your needs. When you are done you can save the document and close Word. You now have the document template contents for your customized Manual Test.
6. Open the file .vstemplate in a text editor such as Notepad. You should see the contents as an XML-formatted document. The document looks like the following.
<VSTemplate Version="2.0.0" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" Type="Item">
<TemplateData>
<Name Package="{52CBD135-1F97-2580-011F-C7CD052E44DE}" ID="113"/>
<Description Package="{52CBD135-1F97-2580-011F-C7CD052E44DE}" ID="109"/>
<Icon Package="{52CBD135-1F97-2580-011F-C7CD052E44DE}" ID="107"/>
<ProjectType>CSharp</ProjectType>
<SortOrder>10</SortOrder>
<DefaultName>ManualTest.mht</DefaultName>
<TemplateGroupID>TestProject-V1</TemplateGroupID>
<TemplateID>TestProject-V1-WordManualTest</TemplateID>
</TemplateData>
<TemplateContent>
<ProjectItem ReplaceParameters="false" OpenInEditor="true">ManualTest.mht</ProjectItem>
</TemplateContent>
<TestProjectData>
<LongDescription Package="{52CBD135-1F97-2580-011F-C7CD052E44DE}" ID="112"/>
<Helpkeyword Package="{52CBD135-1F97-2580-011F-C7CD052E44DE}" ID="105"/>
</TestProjectData>
<WizardExtension>
<Assembly>Microsoft.VisualStudio.QualityTools.Wizard.TestProjectWizards</Assembly>
<FullClassName>Microsoft.VisualStudio.TestTools.TestProjectWizards.TestItemWizardExtension</FullClassName>
</WizardExtension>
</VSTemplate>
Note: In Visual Studio 2008, the Version of the VSTemplate is 3.0.0. If you start with the template from the correct folder you will already have this version set correctly.
At this point the document represents the Manual Test Word format item template. We need to make some changes to add our customized template specific information.
Specifically update the following tags: Name, Description, DefaultName, TemplateID, and ProjectItem. Remove or replace the contents of the TestProjectData tag.
Save the document.
Note: It is very important that the TemplateID is unique. If it matches an existing template it will override its associated document.
Note: If you want to use special characters in the Name or Description of the template you will need to use the equivalent escape character (same XML rules apply to the .vstemplate document). For example, if you want to include a word that contains the French character "é" (no quotes) then you will need to replace it with its equivalent escape character "é" (no quotes). Failing to do so will cause the template to fail registration without any error message.
The following is the resulting InCycleManualTest.vstemplate file used in this example.
<VSTemplate Version="2.0.0" Type="Item" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.microsoft.com/developer/vstemplate/2005">
<TemplateData>
<Name>InCycle Manual Test (Word format)</Name>
<Description>Customized manual template</Description>
<Icon Package="{52CBD135-1F97-2580-011F-C7CD052E44DE}" ID="107"/>
<ProjectType>CSharp</ProjectType>
<SortOrder>80</SortOrder>
<DefaultName>InCycleManualTest.mht</DefaultName>
<TemplateGroupID>TestProject-V1</TemplateGroupID>
<TemplateID>InCycleManualTest</TemplateID>
<ShowByDefault>false</ShowByDefault>
</TemplateData>
<TemplateContent>
<ProjectItem ReplaceParameters="true" OpenInEditor="false">InCycleManualTest.mht</ProjectItem>
</TemplateContent>
<WizardExtension>
<Assembly>Microsoft.VisualStudio.QualityTools.Wizard.TestProjectWizards</Assembly>
<FullClassName>Microsoft.VisualStudio.TestTools.TestProjectWizards.TestItemWizardExtension</FullClassName>
</WizardExtension>
</VSTemplate>
7. Repackage the files you previously extracted and modified into a zip file and call it the same name as the folder you created. In this example, the compressed file is called IncycleManualTest.zip. Verify that the zip file does contain your two files and that these files do have your changes.
Note: It is very important that the files reside in the root of the zip file. If not, the template will not register correctly.
Deploy the Template
8. Copy the modified exported template zip file to your Visual Studio's Item Template folder. In this example, I copy the file IncycleManualTest.zip to my folder D:\Program Files\Microsoft Visual Studio 8\Common7\IDE\ItemTemplates\CSharp\1033.
9. If updating an existing template you must first remove any previous template from Visual Studio’s Item Template Cache, which gets copied during the initial installation.
For example, if updating the IncycleManualTest.zip template I would remove the corresponding IncycleManualTest.zip file from my folder D:\Program Files\Microsoft Visual Studio 8\Common7\IDE\ItemTemplatesCache\CSharp\1033 before installing the new template. This is to ensure the new template is correctly updated in the cache.
10. Install your customized template. For the template installation command to work correctly you need to run the Visual Studio 2005 Command Prompt, as it initializes some environment variables required for the execution of the command.
The Visual Studio 2005 Command Prompt can be found under your Start menu. Look for the program group Microsoft Visual Studio 2005 / Visual Studio Tools. Launch it.
At this point, make sure you close any running instances of Visual Studio. At the command prompt type and execute the command devenv /InstallVSTemplates.
Give it some time to complete. Note that even after the command prompt returns your hard disk may continue spinning. So, give it some more time to make sure the registration is finalized.
Test the Template
11. Test your new template. Launch Visual Studio and open/create a Test Project. Select New Test... like you did before to display the Add New Test dialog. You should now see your new Manual Test template.
In order to do a complete test of this template you should create multiple Manual Test using it and go through the paces to make sure the template is recognized in the Test View.
20 comments:
What if everything you've done to this point is in Excel?
(imagine if you will a small orginization with hundreds and even thousands of manual test cases in Excel format that now has the opportunity to take advantage of VSTE for Testers)
Sorry for taking so long to respond. I have been very busy and I was not able to spend the necessary time to try things out before answering to your question.
There's a post Using Excel as a source for manual Tests in VSTT that is a good start. The problem I see with the method is that it seems to suggest that you should be the one to take care of the creation and association of the manual test. The provided example does not work in the same way as I am describing here, since it does not become an integrated part of the environment.
The good news is that you can use the method I describe above in the post and change it slightly to support Excel as your Manual Test source.
I ran a couple of scenarios myself and managed to get an Excel spreadsheet to be part of a Test Project. Here are the issues I found:
Excel does not store Custom Properties in MHT files
This is problematic since you need to have 2 custom properties: TestType and TestID. The latter is really important because it must hold the value $guid1$ in order for VSTS to assign it an ID automatically.
The work around is to manually modify the MHT file after you have completed the changes in Excel. You would open the file in Notepad or similar editor and add the following in the < head > section.
< !--[if gte mso 9] >< xml >
< o:CustomDocumentProperties >
< o:TestType dt:dt=3D"string" >Manual Test< /o:TestType >
< o:TestID dt:dt=3D"string" >$guid1$< /o:TestID >
< /o:CustomDocumentProperties >
< /xml >< ![endif]-- >
NOTE: I put spaces in some parts of the above example so they don't get processed as HTML during posting.
The problem with this method is that even if you manage to do that, the moment you edit the file in any way in Excel and store it again, the Custom Properties will be lost and VSTS will fail loading the file as a Manual Test.
The default association for MHT files is Word
If you double click on the manual test from within VSTS you will launch Word and it will tell you the file is not the correct format when you save it.
You can go ahead and do the conversion. Once you do this you are now dealing with a Word document and the Custom Properties are maintained.
So, I don't think you will be able to have a clean way to use Excel as Manual Tests, at least not without somehow managing the Custom Properties outside of Excel.
One thing I did not try is embedding an Excel spreadsheet inside a Word document and see if that can be stored in a MHT file. Perhaps you can try that and let us know.
This is great information. Thank you!
It will probably be a couple weeks before the work schedule allows for more investigation on this, but I will definitely keep you posted as progress (or lack thereof) occurs.
(Work always seems to get in the way of getting things done, eh?)
I just ran another set of tests where I created a spreadsheet in Excel and then copied the cells I wanted to bring over to Word. In Word, I pasted the contents as an Excel object. I then saved the file as a MHT file and added it to my template. Once registered, I am now able to create Manual Tests using Excel inside Word and its all good!
BTW, I forgot to mention to remember to add the Custom Properties TestType and TestID. You can do this from within Word and not modify the MHT file directly. I may write a separate blog about using Excel to create Manual Tests.
I'm trying to get this to work in VS 2008, but I am having problems. No matter what I do, the template never seems to change. That is, my new template does not appear in the Add Test dialog, and if I modify the existing Manual Test Word Template, it is still the original format.
Please help.
I will take a look at the steps and apply it to my 2008 VPC. I will update the process accordingly.
In the mean time, you may want to make sure that the folders referenced in the post refer to 2008 and not 2005 paths. Just a thought.
I don't know off hand of anything that has changed in 2008 in this respect.
I just finished going through the exact same steps I documented and the process works for Visual Studio 2008.
The only difference is that you need to make sure you point to the path using Microsoft Visual Studio 9.0 (Visual Studio 2008) instead of Microsoft Visual Studio 8 (Visual Studio 2005). Let me know if you manage to get it going.
For example, C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplatesCache\CSharp\1033.
Thanks Leo. It's working now. I'm not sure what I had wrong, but I cleaned everything out and renamed everything ,adding a "2" to all changed names and that did that trick.
This is a great article and it works for me. I successfully adde my new test template, but know I am wonder how to get the new template included on the menus.
If you right click on a Project, select Add, you will see all of the "standard" test including the original manuat test in Word format. I would like to add my newly created template into that list. That way I do not have to go to Add, New Test, and then slect from the Add New Test dialog.
Any help is appreciated.
I have not taken the time to investigate how this can be done simply. I do know that to add a menu you would need to create an addin for Visual Studio. That is more involved than I would want to get into for such customization. However, I will see if I can find a few minutes to figure out how MS does it.Perhaps, there is a way to add the menu without needing to create your own addin.
Hi Leo,
I have followed your instructions, but the new template is not used in VSTS 2008.
I have changed the path of item templates location (even project templates :p) to point to the location mentioned in this article.
However, all these attempts failed :(
Any idea what may went wrong? What else do I need to pay attention to?
Hope that you could shed some lights here.
Thanks in advance.
Catherine
Most of the time when I ran into this is because there's something wrong in the XML or because the files were not put directly in the root of the ZIP file. If the files are in a folder inside the ZIP file it will not work. Perhaps you can send me your sample to "lvildosola at htcal dot com" and I would be happy to see what may be wrong.
Hi Leo,
I have a problem similiar to John McConda, my new template did not appear in the Add Test Dialog. How can I trouble shoot this? I’ve also read you have mentioned that “Note: It is very important that the files reside in the root of the zip file. If not, the template will not register correctly.” And making sure there’s nothing wrong in the XML, how can I fix/ensure both of these items are correct?
thanx
Hi Leo, is there a way to add an option besides the result
options "pass" or "fail"?
I am not aware of a way to do this. I never looked into it.
However, you can make it part of your template and put it there. You will not be able to report on it, of course, as it will not be a dimension or reportable field.
ok, thanks for the quick response!
I was having difficulty getting the new template to show. Because we've recently upgraded to Office 2007 - and have had a few issues, I tried falling back to saving it as compatible with Office 2003. The template then appeared. This hasn't been thoroughly researched but it may be something to check/try if anyone is having difficulty and using Office 2007.
Hello,
I have a question about this. We have VSTS, but we can't get the manual template to be installed. Is there a possibility that you could send me the .zip you talk about in this article?
Thank you very much.
I would need an address to send it to. Please e-mail me at "info at htcal dot com".
Post a Comment