@prismicio/e2e-tests-utils

@prismicio/e2e-tests-utils

This library comprises utility functions tailored for end-to-end tests at Prismic, with a primary focus on tasks like repository creation, configuration, and deletion.

Purpose

In the context of testing, it's essential to operate in a controlled environment where the necessary conditions are defined explicitly. To avoid redundant logic across various services for setting up test data, this library consolidates and provides the required functionalities.

Installation

npm install --save-dev @prismicio/e2e-tests-utils

Usage

Creating and configuring a repository

Useful to run the tests on a clean repository with a controlled configuration, for example in a CI.

import { createRepositoriesManager } from "@prismicio/e2e-tests-utils";
import type { RepositoryConfig } from "@prismicio/e2e-tests-utils";

const config: RepositoryConfig = {
	locales: ["en-gb", "fr-fr"],
	defaultLocale: "en-gb",
	// ... see RepositoryConfig for other options
};
const authConfig = { email, password };

const testUtils = createRepositoriesManager({ urlConfig :"https://prismic.io", authConfig});
const repository = await testUtils.createRepository(config);

// A repository is now available with a unique name and configured as required
repository.getBaseURL() // https://my-unique-repo-name.prismic.io

// run your tests, delete the repository
await testUtils.tearDown();

Create Custom Types

Use Custom Types and Shared slices typed from the @prismicio/types-internal library. If the custom types already exists on the repository, they will be updated.

import { createRepositoriesManager } from "@prismicio/e2e-tests-utils";

import {
	CustomType,
	SharedSlice,
} from "@prismicio/types-internal/lib/customtypes";

const slice: SharedSlice = {
	id: "test_slice",
	type: "SharedSlice",
	name: "A slice demo",
	// ...
};
const customType: CustomType = {
	id: "test_ct",
	label: "A custom type",
	// ...
	json: {
		Main: {
			slices: {
				type: "Slices",
				fieldset: "Slice Zone",
				config: {
					choices: {
						[slice.id]: {
							type: "SharedSlice",
						},
					},
				},
			},
		},
	},
};

// Create them individually
await repository.createSlices([slice]);
await repository.createCustomTypes([customType]);

// Or create them via the RepositoryConfig object
const config = { slices: [slice], customTypes: [customType] };
await testUtils.createRepository(config);

Retrieve an API token (jwt)

const token = await testUtils.getUserApiToken();

Get API clients

The library provides a few api clients for Prismic services. For example the Content Api.

const contentApi = repository.getContentApiClient();
const document = await contentApi.getDocumentByID(documentId);

The @prismicio/client package could have been used but had too many abstractions (caching, error handling) that we don't necessarly want for test execution.

Retrieve a RepositoryManager of an existing repository

const repository = await testUtils.getRepositoryManager(name);
// configure multiple settings and once
await repository.configure(settings);
// or configure them individually
await repository.createRelease("next release");

How does the library know which endpoints urls to use under the hood (authentication server, custom types api)?

When you create the manager, you have 2 options:

• Provide the base Prismic url, like createRepositoriesManager({ urlConfig: "https://prismic.io", authConfig: credentials }). The library infers the service urls from the base URL like http://authentication.prismic.io
• One a dev environment, you might want to have control over each service url. Use createRepositoriesManager({ urlConfig: { baseURL: "https://...", customTypesApi : "https://...", authenticationApi : "https://..."}, authConfig })

Customise the log level

By default, the library logs each operation, this can be changed:

• Set the environment variable to prismic_e2e_tests_utils_silent to true to remove all logs.
• Set the environment variable to prismic_e2e_tests_utils_log_level to info or debug.