Testing, Debugging, and Deploying SharePoint Framework (SPFx) Solutions (V1)

Testing, Debugging, and Deploying SharePoint Framework (SPFx) Solutions

In the seventh installment of our SPFx development series, we will focus on the critical aspects of testing, debugging, and deploying SPFx solutions. Ensuring your SharePoint Framework applications are robust, error-free, and efficiently deployed is essential for delivering high-quality solutions to users.

This article will guide you through best practices and tools for testing and debugging your SPFx web parts and extensions, as well as strategies for deploying your solutions to SharePoint Online or on-premises environments.

Importance of Testing and Debugging in SPFx Development

Testing and debugging are integral parts of the development lifecycle. They help you identify and fix issues early, ensuring that your SPFx solutions function correctly and provide a smooth user experience. Effective testing and debugging can save time, reduce costs, and prevent potential issues in production environments.

Setting Up Your Development Environment for Testing

Before you can effectively test and debug your SPFx solutions, you need to set up your development environment properly.

1. Using the SharePoint Workbench

The SharePoint Workbench is a testing surface that allows you to test your web parts in a live SharePoint environment.

Local Workbench: Ideal for rapid development and testing without needing a SharePoint site. Run it using gulp serve.

  gulp serve

Access it at https://localhost:5432/workbench.

Online Workbench: Provides a more accurate testing environment by running within SharePoint Online. Access it at https://yourtenant.sharepoint.com/_layouts/15/workbench.aspx.

2. Configuring HTTPS Certificates

SPFx uses HTTPS for development. Ensure your development certificate is set up correctly.

Install the certificate:

  gulp trust-dev-cert

If you encounter issues, you may need to clear and re-trust the certificate:

  gulp untrust-dev-cert
  gulp trust-dev-cert

Debugging SPFx Solutions

Effective debugging helps you identify and resolve issues quickly.

1. Using Developer Tools

Modern browsers like Chrome and Edge offer powerful developer tools.

Console Logging: Use console.log() statements to output variable values and trace execution flow.
Breakpoints: Set breakpoints in your code to pause execution and inspect variables.
Source Maps: Ensure source maps are enabled in your gulp serve task to map minified code back to your original TypeScript code.

2. Remote Debugging

When debugging in the SharePoint Online Workbench or a live SharePoint page, you can attach your debugger to the browser process.

Launch Configuration: Use launch configurations in Visual Studio Code to attach the debugger. Example launch.json configuration:

  {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "SPFx Chrome",
        "type": "chrome",
        "request": "launch",
        "url": "https://localhost:5432/workbench",
        "webRoot": "${workspaceFolder}"
      }
    ]
  }

Start Debugging: Press F5 in Visual Studio Code to start the debugging session.

3. Debugging Extensions

Debugging SPFx extensions (Application Customizers, Field Customizers, Command Sets) requires additional steps.

Update your serve.json configuration in the config folder to specify the page URL and the component manifest ID. Example:

  {
    "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/config.2.0.0.2.json",
    "serveConfigurations": {
      "default": {
        "pageUrl": "https://yourtenant.sharepoint.com/sites/yoursite/SitePages/YourPage.aspx",
        "customActions": {
          "YOUR-EXTENSION-ID": {
            "location": "ClientSideExtension.ApplicationCustomizer",
            "properties": {
              "testMessage": "Test message"
            }
          }
        }
      }
    }
  }

Run gulp serve to load your extension in the specified page.

Unit Testing SPFx Components

Unit tests help ensure individual components function as expected.

1. Choosing a Testing Framework

Common testing frameworks for SPFx include:

Jest: A JavaScript testing framework with a focus on simplicity.
Mocha and Chai: Mocha is a feature-rich JavaScript test framework, and Chai is an assertion library.

2. Setting Up Jest

Install Jest and related packages:

npm install --save-dev jest @types/jest ts-jest

Configure Jest in your package.json:

"jest": {
  "preset": "ts-jest/presets/js-with-ts",
  "testEnvironment": "jsdom",
  "transform": {
    "^.+\\.tsx?$": "ts-jest"
  },
  "moduleNameMapper": {
    "\\.(css|scss)$": "identity-obj-proxy"
  }
}

3. Writing Unit Tests

Create test files alongside your components.

Example MyComponent.test.tsx:

import * as React from 'react';
import { shallow } from 'enzyme';
import MyComponent from './MyComponent';

describe('<MyComponent />', () => {
  it('should render without crashing', () => {
    const wrapper = shallow(<MyComponent />);
    expect(wrapper.exists()).toBe(true);
  });
});

Run tests using:

npm test

Integration Testing

Integration tests verify that different components work together as expected.

Use tools like Selenium WebDriver or Puppeteer for end-to-end testing.
Mock SharePoint data using tools like @pnp/sp mock libraries.

Deploying SPFx Solutions

Once your solution is tested and ready, it’s time to deploy it.

1. Preparing for Deployment

Build the Solution:

  gulp bundle --ship

Package the Solution:

  gulp package-solution --ship

2. Deploying to SharePoint Online

Upload the Package to the App Catalog:
Navigate to your tenant’s App Catalog site (https://yourtenant.sharepoint.com/sites/appcatalog).
Upload the .sppkg file from the sharepoint/solution folder.
Deploy the Solution:
After uploading, a dialog will appear. Check “Make this solution available to all sites in the organization” if desired.
Adding the App to a Site:
Navigate to the site where you want to add the app.
Go to “Site Contents” and click “Add an App”.
Select your app from the list.

3. Deploying to SharePoint On-Premises

Ensure your SPFx version is compatible with your SharePoint Server version (e.g., SPFx 1.4.1 for SharePoint 2016).
Follow similar steps as deploying to SharePoint Online, but use your on-premises App Catalog.

Automating Deployment with CI/CD

Automate your build and deployment process using Continuous Integration and Continuous Deployment (CI/CD) pipelines.

1. Using Azure DevOps

Build Pipeline:
Install Node.js environment.
Run npm install.
Run gulp bundle --ship.
Run gulp package-solution --ship.
Release Pipeline:
Use the “Copy Files” task to collect the .sppkg file.
Use the “Publish Build Artifacts” task.
Deploy to SharePoint using scripts or extensions that interact with SharePoint (e.g., Office 365 CLI, PnP PowerShell).

2. Using GitHub Actions

Create workflows that trigger on push or pull request.
Define jobs to build and package your solution.
Use actions or scripts to deploy the package to SharePoint.

Handling Versioning and Upgrades

Proper versioning ensures smooth upgrades and maintenance.

Versioning the Solution:
Update the version field in package-solution.json.
Versioning Web Parts:
Update the version field in your web part’s manifest.json.
Upgrade Strategies:
For minor changes, you can update the solution without retracting the previous version.
For major changes, consider retracting the old version before deploying the new one.

Best Practices

Code Quality: Use linters like ESLint to maintain code quality.
Documentation: Document your code and deployment processes.
Error Handling: Implement robust error handling in your code.
Performance Optimization: Minimize bundle size, use code splitting if necessary.
Security: Follow security best practices, avoid exposing sensitive data.

Conclusion

Testing, debugging, and deploying are crucial phases in SPFx development. By adopting best practices and leveraging the right tools, you can ensure that your SharePoint solutions are reliable, maintainable, and deliver value to your users.

In the next article of this series, we’ll explore Security, Permissions, and Best Practices in SPFx Development, focusing on how to secure your solutions and adhere to best practices for SPFx development.

Stay tuned for the concluding article of our series, where we’ll wrap up our journey into mastering SPFx development with PnP and Fluent UI.

edvaldo b. guimarães filho

Testing, Debugging, and Deploying SharePoint Framework (SPFx) Solutions (V1)