Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Debug and test a connector

As you develop your integration, refer to this document for tips on how to debug your connector and how to write tests for your connector code.

Debug

As you develop and test your integration, you may need to debug the GraphQL types that the Netlify SDK generates using your connector, or debug the connector itself.

To take advantage of the debugging steps we document below, you need to install the Netlify SDK utility tools.

Make sure your project has dev and build scripts

When you use the SDK’s guided set-up flow to create an integration, we automatically add scripts to your project that run the netlify-integration dev and netlify-integration build commands. If you skipped the guided set-up flow, make sure you manually update your package.json to include "dev": "netlify-integration dev -c" and "build": "netlify-integration build -c".

Debug GraphQL types

To debug the GraphQL types that the Netlify SDK generates using your connector, run:

pnpm run dev

The command starts a local GraphQL server for your connector and outputs a dev-model.gql file to your terminal’s current working directory. The dev-model.gql file contains the GraphQL schema that the Netlify SDK generated from your model definitions.

For example:

type ExampleText {
  contents: String!
}


type ExampleCta {
  title: String!
  link: String!
}


union ExampleBlock = ExampleText | ExampleCta


type ExampleContent {
  title: String!
  blocks: [ExampleBlock]
}

You can review this file to check for any errors.

We recommend that you add dev-model.gql to your .gitignore file to avoid committing it to your repository.

Debug your connector

Since Connectors deal with large amounts of data, the most effective way to debug your connector is to use Node debuggers. You can use console.log() statements also, but we recommend using Node debuggers instead.

For Node debuggers to work, set your IDE to auto-attach to child processes.

The steps to use Node debuggers with your connector will be similar across IDEs. As an example, here is how to run the debugger in VSCode:

  1. Open the command palette (cmd+shift+p on macOS).

  2. Type in JavaScript Debug Terminal and press enter.

  3. VSCode will open a new terminal window. In that terminal, run:

    pnpm run dev

  4. Add breakpoints or type the word debugger in your code to pause on a specific line.

  5. When the debugger pauses, it will highlight the line and you can hover over nearby variables to inspect their runtime values in a pop-up.

  6. Save your code to automatically detach the debugger and restart the process. The debugger will pause again on any new breakpoints you set.

Test connector code

To create a stable connector, you should write tests for your code.

The Netlify SDK includes a contentEngine utility that you can use to run your connector and test locally. contentEngine includes the following testing utilities:

  • sync: simulates a data sync by running connector.sync(fn).
  • stop: stops the contentEngine. This is helpful for resetting after a test suite completes.
  • test: includes the following methods that you can use for testing queries:
    • getNodes: gets all documents.
    • getNodesByType: gets all documents by GraphQL type. The GraphQL type is generated using the document model’s name. For example, Post or Author.
    • query: runs a specified GraphQL query.

Before you run the tests, make sure to build your connector by running:

pnpm run build

The tests will run on the bundled integration.

Here is an example of how to use these testing utilities:

import { contentEngine } from "@netlify/content-engine";


const engine = contentEngine({
  engineConfig: {
    plugins: [
      {
        // the connector must be built before running tests.
        resolve: require.resolve("../.ntli/connector/package.json"),
        options: {
          examplePluginOption: "example",
        },
      },
    ],
  },
});


describe("example tests", () => {
  afterAll(async () => {
    await engine.stop();
  });


  it("Fetches data from the example connector", async () => {
    const syncState = await engine.sync({
      clearCache: true,
    });
    expect(syncState.exitCode).toBe(undefined);


    expect(await engine.test.getNodes()).toHaveLength(9);
    expect(await engine.test.getNodesByType("Author")).toHaveLength(2);
    expect(await engine.test.getNodesByType("Post")).toHaveLength(3);


    const { data, errors } = await engine.test.query(
      /* GraphQL */ `
        query {
          allPost {
            nodes {
              id
              description
            }
          }
        }
      `,
      {}
    );


    expect(errors).toBeUndefined();


    for (const post of data.allPost.nodes) {
      expect(post.description).toBeTruthy();
    }
  });
});

Next steps

When you’re ready, you can publish your integration as a private data integration and test it with your team in production.