@jupiterone/integration-sdk-dev-tools

@jupiterone/integration-sdk-dev-tools

This package contains some common dependencies and configuration files used in JupiterOne integrations.

This module is opinionated and bundles in the following dependencies:

• typescript
• prettier
• jest
• eslint
• husky
• lint-staged

For convenience, this package also comes bundled with the @jupiterone/integration-sdk-cli module.

Installation

npm install -D @jupiterone/integration-sdk-dev-tools

# or

yarn add -D @jupiterone/integration-sdk-dev-tools

Usage

Create prettier.config.js at root of your project that contains:

module.exports = require('@jupiterone/integration-sdk-dev-tools/config/prettier');

Create lint-staged.config.js at root of your project that contains:

module.exports = require('@jupiterone/integration-sdk-dev-tools/config/lint-staged');

Create husky.config.js at root of your project that contains:

module.exports = require('@jupiterone/integration-sdk-dev-tools/config/husky');

Create jest.config.js at root of your project that contains:

module.exports = require('@jupiterone/integration-sdk-dev-tools/config/jest');

Create tsconfig.json at root of your project that contains:

{
  "extends": "./node_modules/@jupiterone/integration-sdk-dev-tools/config/typescript",
  "compilerOptions": {
    "outDir": "dist"
  },
  "exclude": ["dist"]
}

Create a .eslintrc at the root of your project that contains:

{
  "root": true,
  "extends": [
    "./node_modules/@jupiterone/integration-sdk-dev-tools/config/eslint.json"
  ]
}

Changelog

[8.4.0] - 2022-02-16

Fixed

• Changed logger to fully mask config field values, rather than displaying last 4 chars

Added

• Added .toMatchStepMetadata jest matcher. This matcher complements the executeStepWithDependencies utility. Usage:

  const stepResult = await executeStepWithDependencies({
    stepId: Steps.FETCH_USERS.id,
    invocationConfig,
    instanceConfig,
  });
  
  expect(stepResult).toMatchStepMetadata({
    stepId: Steps.FETCH_USERS.id,
    invocationConfig,
  });
  

• Updated jest matchers in the following way:

  • added optional _type argument to .toMatchGraphObjectSchema matcher
  • added optional _type and _class arguments to .toMatchDirectRelationshipSchema matcher

  This enables developers to simply pass the StepEntityMetadata and StepRelationshipMetadata interfaces to these matchers. Usage:

  expect(collectedEntities).toMatchGraphObjectSchema(Entities.USER);
  expect(collectedRelationships).toMatchDirectRelationshipSchema(
    Relationships.ACCOUNT_HAS_USER,
  );
  

• Added optional schema property to StepGraphObjectMetadata. This allows developers to provide the property schema to expect on entities, relationships, and mapped relationships. This serves two uses:

  1. Schemas can be used at runtime or test-time to verify that an entity has the correct properties
  2. The j1-integration document command could automatically produce consumer documentation about the properties that an entity / relationship is expected to have

• Added executeStepWithDependencies utility to @jupiterone/integration-sdk-testing package. This allows developers to test specific integration steps in isolation, while assuring that all of its dependencies have indeed executed. Usage:

  const { collectedEntities, collectedRelationships, collectedData } =
    await executeStepWithDependencies({
      stepId: Steps.FETCH_USERS.id,
      invocationConfig,
      instanceConfig,
    });
  
  expect(collectedEntities.length).toBeGreaterThan(0);
  expect(collectedEnities).toMatchGraphObjectSchema({
    _class: Entities.USER._class,
    schema: Entities.USER.schema,
  });
  // ... additional expectations
  

• Added MockJobState.collectedData to capture data that has been collected in the job state. Usage:

  const jobState = createMockJobState({
    setData: { existingKey: 'existing-value' },
  });
  await executeStepThatAddsAccountEntity();
  
  expect(jobState.collectedData).toEqual({
    ACCOUNT_ENTITY: {
      _type: 'account',
      _class: 'Account',
      _key: 'account1',
    },
  });
  expect(jobState.collectedData.existingKey).toBeUndefined();