Debugging

With the release of 2.0 we wanted to enhance the debugging story for the library both when consuming it in other applications and working on library features. This page outlines debugging in various scenarios.

Debugging Library Features in Code using Node

The easiest way to debug the library when working on new features is using F5 in Visual Studio Code. This uses the launch.json file to build and run the library using debugging/debug.ts as the program entry. You can add any number of files to this directory and they will be ignored by git, however the debug.ts file is not, so please ensure you don't commit any login information.

Setup settings.js

If you have not already you need to create a settings.js files by copying settings.example.js and renaming it. Then update the clientId, clientSecret, and siteUrl fields in the testing section.

Test your setup

If you hit F5 now you should be able to see the full response from getting the web's title in the internal console window. If not ensure that you have properly updated the settings file and registered the add-in perms correctly.

Create a debug module

Using example.ts as a reference create a debugging file in the debug folder, let's call it mydebug.ts and add this content:

// note use of relative paths to the modules
import pnp from "../src/pnp";
import { Logger, LogLevel, ConsoleListener } from "../src/utils/logging";
import { ListEnsureResult } from "../src/pnp";

export function MyDebug() {

    // run some debugging
    pnp.sp.web.lists.ensure("MyFirstList").then((list: ListEnsureResult) => {

        Logger.log({
            data: list.created,
            message: "Was list created?",
            level: LogLevel.Verbose
        });

        if (list.created) {

            Logger.log({
                data: list.data,
                message: "Raw data from list creation.",
                level: LogLevel.Verbose
            });

        } else {

            Logger.log({
                data: null,
                message: "List already created!",
                level: LogLevel.Verbose
            });
        }
    });
}

Update debug.ts to launch your module

First comment out the import for the default example and then add the import and function call for yours, the complete updated debug.ts should look like this:

declare var require: any;
import pnp from "../src/pnp";
import { Logger, LogLevel, ConsoleListener } from "../src/utils/logging";

// setup the connection to SharePoint using the settings file, you can
// override any of the values as you want here, just be sure not to commit
// your account details :)
// if you don't have a settings file defined this will error
// you can comment it out and put the values here directly, or better yet
// create a settings file using settings.example.js as a template
let settings = require("../../settings.js");

// configure your node options
pnp.setup({
    nodeClientOptions: {
        clientId: settings.testing.clientId,
        clientSecret: settings.testing.clientSecret,
        siteUrl: settings.testing.siteUrl
    }
});

// setup console logger
Logger.subscribe(new ConsoleListener());
Logger.activeLogLevel = LogLevel.Verbose;

// importing the example debug scenario and running it
// adding your debugging to other files and importing them will keep them out of git
// PRs updating the debug.ts or example.ts will not be accepted unless they are fixing bugs
// add your debugging imports here and prior to submitting a PR git checkout debug/debug.ts
// will allow you to keep all your debugging files locally
// comment out the example
// import { Example } from "./example";
// Example();

import { MyDebug } from "./mydebug"
MyDebug();

// you can also set break points inside the src folder to examine how things are working
// within the library during your debugging calls!

Debug!

Place a break point within the promise resolution in your debug file and hit F5. Your module should be run and your break point hit. You can then examine the contents of the objects and see the run time state. Remember you can also set breakpoints within the src folder to see exactly how things are working during your debugging scenarios.

Next Steps

Using this pattern you can create and preserve multiple debugging scenarios in separate modules locally.

In Browser Debugging

With the 2.0 release we have improved the watch/serve features of the library to improve the debugging experience in the browser. The development server will run continuously until you cancel it (Ctrl + C) and watch the /src folder for any changes. So you can make updates to the library and then hit F5 in the browser to see your changes.

Start the local serve

gulp serve

Add reference to library

Within a SharePoint page add a script editor web part and then paste in the following code:

<script src="https://localhost:8080/assets/pnp.js"></script>
<script>
    alert($pnp.util.getRandomString(10));
</script>

You should see an alert with a random string.

Next Steps

You can make changes to the library and immediately see them reflected in the browser. Also, you can make much more complex scenarios other than just showing an alert :)

Debugging in SPFx

If you are working with the library in the context of the SharePoint Framework and would like to debug your local changes in that context you can easily.

Add External Reference

Within the SharePoint Framework's config/config.js folder add an external reference to your locally served file:

"sp-pnp-js": "https://localhost:8080/assets/pnp.js"

Start Local Servers

Within the sp-pnp-js project start the local server

gulp serve

Within the SPFx project start the local server

gulp serve

This allows you to serve the local sp-pnp-js file directly to your local SPFx project so you can work with both directly. Additionally because source maps are available you will be able to debug both your SPFx code as well as the sp-pnp-js library.