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.

Debug GraphQL types

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

pnpm run dev

yarn dev

npm 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
   • yarn
   • npm

   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 sync event.
• 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 nodes.
  • getNodesByType: gets all nodes by GraphQL type. The GraphQL type is generated using the node 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

yarn build

npm run build

The tests will run on the bundled integration.

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

import { contentEngine } from "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();
    }
  });
});