crds-cypress-contentful

Contentful Tools

This package provides a couple tools to make accessing Contentful from Cypress tests and using results easier.

Tools include:

• Contentful Query Plugin requests information from Contentful
• Query Builders construct correctly formatted queries by configuration
• Text Normalizer strip markdown, special characters, extra whitespace etc. from given text to make comparing text from content and browser easier

Install

Install with

npm install crds-cypress-contentful --save-dev

Required Environment Variables

CONTENTFUL_SPACE_ID
CONTENTFUL_ACCESS_TOKEN
CONTENTFUL_ENV

Contentful Query Plugin

Setup

This tool works best when used as a cy.task(). To configure this, add the following to the cypress/plugins/index.js file:

const contentfulPlugin = require(`crds-cypress-contentful`);

function addContentfulTasks(on, config){  
  const spaceId = config.env.SPACE_ID;
  const environment = config.env.ENVIRONMENT;
  const accessToken = config.env.ACCESS_TOKEN;
  
  const qp = contentfulPlugin.ContentfulQueryPlugin(spaceId, environment, accessToken);   
  on('task', qp);
}

module.exports = (on, config) => {
  addContentfulTasks(on, config);
  return config;
};

This adds the following cy.task commands:

cy.task('getCNFLResource', options);
cy.task('getCNFLResourceById', options);

While using this tool as a plugin is preferred, the class can also be called directly in the test files. Function calls must be wrapped with cy.wrap() for them to included correctly with Cypress's internal stack.

const contentfulPlugin = require(`crds-cypress-contentful`);

describe('Query Contentful as non-plugin', () => {
  let contentfulQuery;
  before(() => {
    const spaceId = Cypress.env('SPACE_ID');
    const environment = Cypress.env('ENVIRONMENT');
    const accessToken = Cypress.env('ACCESS_TOKEN');
    
    contentfulQuery = contentfulPlugin.ContentfulQueryPlugin(spaceId, environment, accessToken);
  });
  
  it('Makes the query', () => {
    cy.wrap(contentfulQuery.getCNFLResourceById('123'))
    .then((resource) => {
      ...
    });
  });
});

Usage

In a test, call the cy.task() command and retrieve the results from a .then() clause.

it('Fetches entries', () => {
  const seriesQuery = "content_type=series&select=fields.title,fields.slug&limit=2"
  cy.task('getCNFLResource', seriesQuery)
  .then((seriesList) => {
    expect(seriesList).to.be.an('array');
    expect(seriesList[0].title.text).to.eq('some title');
    ...
  });
});

it('Fetches entry by id', () => {
  const seriesId = "123"
  cy.task('getCNFLResourceById', seriesId)
  .then((series) => {
    expect(series).to.have.property('title');
    expect(series.title.text).to.eq('some title');
    ...
  });
});

To retrieve an asset, an options object must be used instead of a string since the cy.task() command only accepts one argument.

it('Fetches assets', () => {
  const queryParams = 'fields.contentType[contains]=image&limit=2';
  const options = { queryParams, type: 'assets'};
  cy.task('getCNFLResource', options)
  .then((imageList) => {
    expect(imageList).to.be.an('array');
    expect(imageList[0].title.text).to.eq('some title');
    ...
  });
});

it('Fetches asset by id', () => {
  const id = '123';
  const options = { id, type: 'assets'};
  cy.task('getCNFLResourceById', options)
  .then((image) => {
    expect(image).to.have.property('title');
    expect(image.title.text).to.eq('some title');
    ...
  });
});

Query Builders

These helper classes lets a user "configure" the parameters of a query to generate the query parameters needed by the getCNFLResource function. The ContentfulQueryBuilder class automatically adds a request for sys.id and sys.type if the 'select' parameter is set, and sub-classes SeriesQueryBuilder, MessageQueryBuilder and PromoQueryBuilder also add 'searchFor' parameters to ensure the results are also 'published' on crossroads.net. All these classes can be imported an used directly in the test file.

import { ContentfulQueryBuilder, SeriesQueryBuilder } from 'crds-cypress-contentful';

it('Builds a query for content blocks', () => {
  const qb = new ContentfulQueryBuilder('content_block');
  qb.searchFor = 'fields.category[exists]=true';
  qb.orderBy = '-fields.title';
  qb.select = 'fields.title,fields.slug';
  qb.limit = 2;

  const queryParams = qb.queryParams;
  cy.task('getCNFLResource', queryParams)
  .then((contentBlockList) => {
    expect(contentBlockList).to.be.an('array');
    ...
  });
});

it('Builds a query for Series', () => {
  const qb = new SeriesQueryBuilder();
  qb.orderBy = '-fields.published_at';
  qb.limit = 1;

  const queryParams = qb.queryParams;
  cy.task('getCNFLResource', queryParams)
  .then((series) => {
    expect(series).to.have.property('title');
    ...
  });
});

Text Normalizer

This helper function removes markdown, special characters, newlines and extra whitespace to make it easier to compare text retrieved from Contentful with text retrieved from a page's element. This function uses document.createElement() to interpret markdown as a browser would, so it must be run in a context where this function is available.

import { normalizeText } from 'crds-cypress-contentful';
let currentSeries;
before(() => {
  cy.task('getCNFLResourceById', '123seriesId')
  .then((series) => {
    currentSeries = series;
  });
});

it('Normalizes Contentful and element text', () => {
  cy.visit('/some-page');
  cy.get('#text-field')
  .should('have.prop', 'textContent')
  .then(normalizeText)
  .then((normalElementText))
      const normalContentfulText = normalizeText(currentSeries.description.text);
      expect(normalContentfulText).to.contain(normalElementText);
    });
});