@slack-wrench/blocks-to-image

Blocks To Images

Render Slack Block Kit json as images.

As a side effect, you are also validating the correctness of the JSON you're using, since it won't render if given invalid JSON.

This pairs amazingly with jest-image-snapshot for image-based snapshot testing. No more staring at long json files for hours!

Block Kit Builder is authenticated, if you use this package and want to help make this package easier to use, Send Slack a Message asking them to prioritize them making it unauthenticated.

Table of Contents

• Table of Contents
• Install
• Usage
  • login
  • imageFromBlocks
  • Advanced Configuration
  • jest globalSetup

Install

yarn add --dev @slack-wrench/blocks-to-image
# or
npm install --save-dev @slack-wrench/blocks-to-image

Usage

import BlockKitRenderer from '@slack-wrench/blocks-to-image';
import { toMatchImageSnapshot } from 'jest-image-snapshot';

// Import how you generate Slack Block kit JSON.
import MySlackBlock from './MySlackBlock';

expect.extend({ toMatchImageSnapshot });

const imageCompareOptions = { customDiffConfig: { threshold: 0.1 } };

describe('My Awesome App', () => {
  // We use the block kit builder, it can take a while
  jest.setTimeout(30000);
  let blockKitRenderer: BlockKitRenderer;

  beforeAll(async () => {
    blockKitRenderer = new BlockKitRenderer();

    // Log into a Slack Workspace that's installed block kit builder
    await blockKitRenderer.login(
      process.env.SLACK_DOMAIN || '', // eg: `community` (emit the `.slack.com)
      process.env.SLACK_EMAIL || '',
      process.env.SLACK_PASSWORD || '',
    );
  });

  afterAll(async () => {
    // Cleanup resources
    await blockKitRenderer.close();
  });

  it('Looks beautiful!', async () => {
    const blockImage = await blockKitRenderer.imageFromBlocks(MySlackBlock());

    expect(blockImage).toMatchImageSnapshot(imageCompareOptions);
  });
});

The function toMatchImageSnapshot takes in an optional configuration object customDiffConfig that customizes the snapshot comparison. To avoid test failures due to small differences in the image snapshot comparison, increase the threshold value that is used by jest-image-snapshot. With the default threshold value of 0.01, minor color differences in screenshots would trigger a test failure. For additional information about the configuration, visit the API documentation of jest-image-snapshot.

login

blockKitRenderer.login(
    domain: string, // The domain to your slack workspace eg: `community` (emit the `.slack.com)
    email: string, // The email you use to log into the workspace above
    password: string, // The password you use for the account
) => Promise<Screenshot>

This package uses Slack's Block Kit Builder to render images. You need to log into a workspace that has Block Kit Builder installed.

imageFromBlocks

blockKitRenderer.imageFromBlocks(
    blocks: KnownBlock[], // Blocks that you want to render
    options: ScreenshotOptions = {}, // Screenshot Options
) => Promise<Screenshot>

For details on additional options, see Puppeteer docs

imageFromView

blockKitRenderer.imageFromView(
    view: View, // Modal or App Home that you want to render
    options: ScreenshotOptions = {}, // Screenshot Options
) => Promise<Screenshot>

For details on additional options, see Puppeteer docs

imageFromAttachments

blockKitRenderer.imageFromAttachments(
    attachments: MessageAttachment[], // Attachments that you want to render
    options: ScreenshotOptions = {}, // Screenshot Options
) => Promise<Screenshot>

For details on additional options, see Puppeteer docs

Advanced Configuration

blocks-to-image uses Puppeteer to generate images. If you need to pass additional configuration to Puppeteer, like maybe a custom chrome executable, you can do so in the constructor:

blockKitRenderer = new BlockKitRenderer({
  puppeteer: {
    product: 'firefox',
    headless: false,
    executablePath: '/path/to/exe',
  },
});

Use an existing browser

If you're looking to connect to an existing browser instance, (for example, to speed up jest), you can do so with connect, passing additional configuration.

blockKitRenderer.connect(options: ConnectOptions) => Promise<void>

You can do this before or after logging in depending on your use case.

jest globalSetup

To save some time if you're running this in multiple test files with jest, you can with some additional setup use jest to login only once at the beginning of testing.

Follow [the jest instructions for custom puppeteer hookup], providing blockKitRenderer.browser as the browser in the setup.js and doing the login as part of the setup in the puppeteer_environment.js file. This can speed things up pretty dramatically.