SharePoint Framework debug unit tests and TDD

SharePoint Framework unit tests React setup and prerequisites

Have a look how to setup your SPFx solution for React unit testing here

Debug SharePoint Framework unit test

In this post I will try to explain how you can debug SPFx unit tests, but also how you can run them in parallel with the local Nodejs server (gulp serve) so you can do TDD if you'd like. This short video can give better understanding on how you can do SPFx unit test debugging.

It is simple, there is a gulp command to run the SPFx unit test in debug mode.

gulp test --debug

This command will start Karma server at http://localhost:9876/ so that url can be copied in any modern browser and its debugging tools can be used to further debug the unit tests along with the SPFx React component.

I am using Chrome so at the picture I already opened the address in it and there is a `debug` button at the top right corner.

spfx unit tests debug in chrome and karma

Click on the button and this should redirect to another blank browser page at http://localhost:9876/debug.html. Now this is where we can debug the code and I would use the Chrome Developer Tools (F12) to debug.

SPFx unit tests debug with Karma server and Nodejs

Use Chrome Developer Tools to debug SPFx unit tests

If we open the Chrome Developer Tools (F12) and navigate to the Sources tab then expand the top folder in the left pane, then navigate to


and double click to open the tests.js in Chrome we can see that all the SPFx webpart code along with the unit tests is in the file. It is not ideal, but give us the chance to add breakpoints and debug the SPFx unit tests along with the React component.

The "debugger" keyword to create SPFx unit test breakpoints in Chrome

We can place debugger keyword where we would like to stop the execution of the code and debug from there like that:

it('should welcome element exist', () => {
    // Define the css selector.
    let cssSelector: string = '.ms-font-xl .ms-fontColor-white';

    // Find the elemet using css selector.
    let element: ReactWrapper<React.AllHTMLAttributes<{}>> = reactComponent.find(cssSelector);


So we are debugging JavaScript in an old school way from the browser. It is not perfect, if a developer is used to do that from Visual Studio, but after all a React SPFx component is really JavaScript and debugging from browser should be something familiar for JavaScript developer. If someone has better solution, please let me know in the comments.

SharePoint Framework Test Driven Development

SPFx web part test driven development (TDD) is possible since we use modern JavaScript frameworks. Test-driven development (TDD) is a software development process that relies on the repetition of a very short development cycle: Requirements are turned into very specific test cases, then the software is improved to pass the new tests, only. Have a look at that article from Wikipedia since there are some really good reasons to do TDD. I try to do it and also encourage my teammates to try it because of two reasons:

Create unit test first and refactor the react component code after keeps the code base clean and loosely-coupled. Crafting programs like that shows some code dependencies in advance that we couldn't catch if unit test is not in place.

If SPFx unit tests fails, Visual Studio Team Services can break the build with notifications, so less regression in long term.

There is a short video to show you how to get started with SPFx Test Driven Development

My experience shows that If we dedicate time for unit tests at the end of the sprint then we might not have that time and sacrifice the tests task and never create them which is really bad practice prone to regression and software bugs later.

Debug the React component at the same time with the SPFx unit test

Sometimes a test can fail and the reason may not be obvious and further investigation should be performed. One of the ways to do that is when the unit tests run to add a break point also in the React component that is actually tested. That way when the component is mounted we will hit the breakpoints within React component method, life cycle event, state change etc. For example, we might want to simulate click and verify the result, but for some reason the click handler does not return the correct assertion and should be debugged. Then we add breakpoint to both, the unit test and the button handler to observe the execution line by line.

// Unit test. 
// Simulate button click and see if text has changed.
it('should has SharePoint Patterns and Practices text after click', () => {

    let welcomeText: string = reactComponent.find('.ms-font-xl .ms-fontColor-white').text();

    expect(welcomeText).to.equal("Welcome to SharePoint Patterns and Practices (PnP)!");

// Button click handler in the React Component.
private _buttonHandler(): void {

    this.setState((prevState: IReactTestingPart3State, props: IReactTestingPart3Props): IReactTestingPart3State => {
      prevState.greetings = "Welcome to SharePoint Patterns and Practices!";
      return prevState;


If we debug we will see that the "(PnP)" text is missing in the handler, this is why the test fails and sometimes it is handy to debug both the react component and the unit test to see what is wrong.


We the software developers, love to craft programs! This is a creative process and we are always keen to see the final result. However, we sometimes forget that to bring a program to live is just the start, but we are also responsible to make it error and bug free in long term and the regression can be less if we add at least few unit tests that would cover the business logic and some edge cases. Ideally add the unit tests before the methods :)

SPFx React Unit Testing Sample in Github

Sharing is caring

Tracy | 09 Mar 2018

Hi Velin!
I'm having some problems getting unit testing to work within the SPFx when including external dependencies, and wondering if you might have some insight. For convenience, I posted the question on SE:

Velin Georgiev | 13 Mar 2018

Hey Tracy, you can add the jsChart to the devDependencies. Doing that the tests will run and in the same time the jsChart would not be bundled with the packages, but the packages will use your external dependency. Hope that clears your ask.