Join 34,000+ subscribers and receive articles from our blog about software quality, testing, QA and security.

TestRail and TFS integration


We’re quite new working with TestRail and want to integrate it better with TFS. Ideally, whenever a defect is recorded via TestRail into TFS, I’d like TFS’s Bug ID to populate the Defects field in TestRail - can anyone help with how to do that?

Also, how do I link a project in TestRail with user stories stored in TFS?



In the Administration section of TR - there is an Integration option. You need to provide TFS URLs for Defects. In TR you would add in a Defect and it will open the Web TFS to enter in the defects and when saved it adds a link in the defects to the TFS PBI.

Don’t know how to link projects in TR with user stores or if it can be done though…


Hello Ben,

Thanks for your posting. You can integrate TFS with TestRail with test results (Defects field) as well as test cases (References field). As Brian already mentioned (thanks!), the documentation for this can be found here:

User stories would usually be linked on the test case level using the References field:

In addition to seeing the links to your user stories when viewing a test case/test, you can also add the user stories to your case/test tables (with the Select Columns button) or generate user story related reports on the Reports tab (e.g. a coverage report).

I hope this helps!



Thanks both. However, I’ve added the References URL into the Integration page in the project, but I still can’t get user stories to appear.
When I’m making a new test case, should I be able to select user stories in the References field on that form?



Thanks for the feedback. When you configure the Reference URLs, TestRail would automatically link any entered ID to TFS so you can easily click on it and jump to the relevant entry in TFS. The same would work for defects as well as links in e.g. the coverage reports. The reference titles aren’t currently retrieved and TFS limited / undocumented API would make this difficult. You can learn more here:

The good news is that it appears that Microsoft is opening their API (currently with Visual Studio Online and soon likely with TFS as well) so we can build a better integration. We also plan to extend the reference integration in general to e.g. support the look up feature as well eventually.

I hope this helps.



Is there any new news from Microsoft about this TFS API?

This deeper integration would help a lot on our plans to extent TertRail usage.

Br, Joni


Hi Joni,

We currently don’t have an update but TFS now has a better and more generic API to use for integrations and it’s planned to look into this. Happy to add another vote, thanks for your feedback :slight_smile:



I am just starting to look into writing my own TFS defect plugin. You mention the more generic API, can you point me in the right direction for the documentation of that API?


Hi John,

Yep, sure. You can find the new REST API here:

This looks like an API you can access with every standard HTTP client and you can take a look at one of the built-in defect plugins on how to access it from TestRail (http::get/http::post). Please let me know in case any questions come up, happy to help.



I’m at my first road block. It looks like I don’t have the connection to TFS correct. I’m getting this error when I hover over a linked defect number.

returned an error: error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol

Any ideas?


Hi John,

This looks like an SSL related error and it seems that either your client or server doesn’t support SSL 2/3 (which is a good thing because this is now considered an insecure protocol). Can you check with your IT if your server runs with SSL 2/3?



I solved my connection issue. I was using https instead of http. So now I’m trying to lookup a defect but I get “Undefined property” error and the URL.


Hi John,

Can you please provide a screenshot of the error you see and ideally the configuration under Administration > Integration? You can also send them to our help desk at Can you also try the Push feature on the Add Result dialog?



I have successfully created a TFS defect plugin. I can hover over either the reference number or defect number and see the details. I can also push a defect to TFS that includes a hyperlink back to the test case and the selected iteration path.

So if any one is trying to integrate TFS and TestRail, I can help.


I do have one question.

My test case has a reference number from TFS. When I push a defect to TFS I want to use that reference number to add a relationship link in TFS. I already know how to add do that.

Is that reference number accessible?

To get the title of the test case is use “$test->case->title”

What other fields can I access this way?



I found it, $test->case->refs.


Hey John, do you have the tfs plugin file that you can share? I’d like to get it working for me as well



We have just started using TestRail with VSTS, so a defect plugin that can retrieve defect titles and push defects to VSTS would be amazing.

Is TFS/VSTS a minority usage case for TestRail? There are very few posts about it in the forum


I think I am the only one using TestRail with TFS. I wrote my own plugin to push defects to TFS that we use everyday. If you need some guidance I can help.


We use TFS but we do not use the API - we just use it to list defects IDs in TR. We are a tiny team QA team and the effort to use the APIs would take away from our QA work too much.