npm package: @prismicio/e2e-tests-utils
Description: A collection of utilities for to manage Prismic test data
Author: Prismic
Latest version: 1.17.0

# @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

```bash
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.

```typescript
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.

```typescript
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)

```typescript
const token = await testUtils.getUserApiToken();
```

### Get API clients

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

```typescript
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

```typescript
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`.