prismicio / prismic-mock Goto Github PK

Allowing strings as seeds will make writing tests easier and more reliable.

For example, the following could be done with AVA:

import test from 'ava'
import * as mock from '@prismicio/mock'

test('my test', (t) => {
  const model = mock.model.customType({ seed: t.title })
  const document = mock.value.document({ seed: t.title, model })

 // Do something with the model and document
})

The seed is now connected to the test's title which will be unique within the file.

Is your feature request related to a problem? Please describe.

When writing tests involving @prismicio/client or the Prismic REST API directly, @prismicio/mock can be used to mock return values. Currently this can be done by manually setting up a mock API within tests, such as through a custom request handler via Mock Service Worker (MSW).

Setting this up per-project can be a hassle as it requires intricate URL parameter and authentication checks.

Describe the solution you'd like

A test-specific mock API solution could be provided by @prismicio/mock. There are many ways to do this, such as building a full HTTP server or providing a mocked fetch function.

Rather than build a completely custom solution, it makes sense to integrate with an existing HTTP mocking solution. Mock Service Worker, as mentioned above, is a common library made specifically for this purpose.

@prismicio/mock could export MSW REST API handlers that cover most mocking cases. Its purpose is not to reimplement the Prismic REST API. Instead, it is just the bridge between an HTTP request and a set of provided results.

Preparing an API handler with MSW could look something like this:

import * as prismicM from "@prismicio/mock";
import * as mswNode from "msw/node";

const server = mswNode.setupServer();

const queryResponse = prismicM.api.query({
	documents: [
		prismicM.value.document(),
		prismicM.value.document(),
	],
});

server.use(prismicM.msw.queryHandler({ queryResponse }));

It uses the existing mock generators which allows users to fine-tune the results.

To restate, the provided handlers do not re-implement the REST API. A request with special parameters, such as predicates or fetchLinks, is not processed by the handler. Instead, the user must prepare the response manually.

The handler can, however, validate against the URL to ensure the correct URL was requested.

Describe alternatives you've considered

The following libraries implement API mocking manually using MSW and @prismicio/mock (or @prismicio/types with manual mocks):

• @prismicio/client
• @prismicio/react
• gatsby-source-prismic
• gatsby-plugin-prismic-previews

Additional context

Stripe provides a similar solution via a Docker container: https://github.com/stripe/stripe-mock

Rather than integrating with a specific language and framework, it exposes an API endpoint that returns static mock data. This makes it compatible with any solution, provided test requests are routed to the local URL.

Is your feature request related to a problem? Please describe.

Creating Rich Text and Title mock values is currently limited. It generates values for most block types, such as headings and images, but does not include some like links.

Rich Text and Title mock values can be customized using "pattern" option. Depending on the selected pattern, such as "short" and "long", the length of the value can be loosely determined. This gives some control of the output, but does not allow for custom patterns.

Describe the solution you'd like

To give more control over the created mock value, access to individual block value generators can be provided by the library. This allows users to create custom values like:

• Heading 1
• Paragraph
• Paragraph

This can be useful when you have a general idea of the type of content that will be provided by editors.

This requires all block types to be supported, including links.

Someone could use the individual value generators like this:

import * as prismicT from '@prismicio/types'
import * as prismicM from '@prismicio/mock'

const richTextValue: prismicT.RichTextField = [
  prismicM.value.richTextBlocks.heading1({ pattern: 'medium' }),
  prismicM.value.richTextBlocks.paragraph(),
  prismicM.value.richTextBlocks.paragraph(),
]

Describe alternatives you've considered

Mock values can be constructed by hand. Some guidance is provided thanks to @prismicio/types. Manually creating mock values is not ideal for obvious reasons.

Additional context

N/A

Is your feature request related to a problem? Please describe.

All fields except Links return values that have been filled in. Most uses of the library will expect a filled value, but there are times were an empty value must be tested.

For example, if a React component displays an image from an Image field, it should be tested when an image is provided and not provided.

Describe the solution you'd like

Link mock value generators accept a isFilled option. All value generators could accept this. If isFilled is false, an empty value should be returned.

For an image field, this is different from simply returning null. Instead, it should look like this:

{
  "url": null,
  "dimensions": null,
  "alt": null,
  "copyright": null
}

Describe alternatives you've considered

The returned values can be modified manually. In the image example above, each property can be set to null after a value is created.