Skip to content
Netlify SDK Docs Netlify SDK Docs 2.15.0

Debug and test a connector

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

Run your connector locally

Before you begin, make sure you review the docs for how to run your connector locally and complete the set-up steps. This includes setting local configuration options and specifying a frontend site for visual editor.

Debug

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

Make sure your project has dev and build scripts

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

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 VS Code:

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

  2. Type in JavaScript Debug Terminal and press enter.

  3. VS Code 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 extension.

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 extension as a private extension and test it with your team in production.

Got it!

Your feedback helps us improve our docs.