Accessing Prismic Releases Programmatically

I have been working with the Prismic CMS for the past several months and ran into a problem running Cypress E2E tests with Prismic data that was not yet in a published release.

The tests fail because the Prismic data isn’t available (not published) and the view isn’t rendered.

When you are developing locally there is no issue, because you have access to the release preview link, but I needed a way to access Prismic releases programmatically in my staging and testing environments.

I am primarily querying by Uid in a Node environment which looks like this:

api.query(
  Prismic.Predicates.at('my.docName.uid', 'uid')
);

The Prismic docs mention a query option ref, so I could simply create an env variable and pass it in like this:

api.query(
  Prismic.Predicates.at('my.docName.uid', 'uid'),
  {
    ref: process.env.PRISMIC_RELEASE_REF
  }
);

I also need to create a token that allows refs other than master be queried. That can be found at https://your-repository-name.prismic.io/settings/apps > API & Security.

The final step is finding my release ref uid. An easy way to find it is in the Prismic API browser which is located at:
https://your-repository-name.prismic.io/api/v2

or when you init the api the refs are listed under data.refs

Plug that into your config and you’ll be off and running with passing E2E tests. ✅