@prismicio/e2e-tests-utils 1.0.0-alpha.1

package/src/managers/repositories.ts

@@ -0,0 +1,194 @@
+import { Credentials } from "../types";
+
+import {
+	AuthenticationClient,
+	createAuthenticationApiClient,
+} from "../clients/authenticationApi";
+import { createCustomTypesApiClient } from "../clients/customTypesApi";
+import { WroomClient } from "../clients/wroom";
+import { EnvVariableManager } from "../utils/envVariableManager";
+import { logHttpResponse, logger } from "../utils/log";
+import { randomString } from "../utils/random";
+
+import { RepositoryConfig, RepositoryManager } from "./repository";
+
+/**
+ * Factory method to create a RepositoriesManager to manage repositories test
+ * data.
+ *
+ * @param urlConfig - If provided as an object:
+ *
+ *       - {@link UrlConfig.baseURL}: The Prismic base URL.
+ *       - {@link UrlConfig.customTypesApi}: The base URL for the Custom Types API.
+ *       - {@link UrlConfig.authenticationApi}: The base URL for the Authentication API.
+ *
+ *   If provided as a string: It is treated as the base URL for Prismic. Other
+ *   URLs (Custom Types API, Auth API) will be derived from it.
+ * @param auth - The authentication credentials
+ *
+ * @returns An instance of {@link RepositoriesManager} to manage test data.
+ */
+export const createRepositoriesManager = (
+	urlConfig: UrlConfig | string,
+	auth: Credentials,
+): RepositoriesManager => {
+	return new RepositoriesManager(urlConfig, auth);
+};
+
+/** Utility object to manage Prismic test data */
+export class RepositoriesManager {
+	private readonly urls: UrlConfig;
+	private readonly wroomClient: WroomClient;
+	private readonly authClient: AuthenticationClient;
+	/**
+	 * helper to keep track of repositories across independent test phases (setup,
+	 * teardown)
+	 */
+	private readonly repositories = new EnvVariableManager(
+		"_PRISMIC_E2E_TESTS_REPOS",
+	);
+
+	/**
+	 * @param prismicUrl - The base URL of the Wroom app.
+	 * @param credentials - Authentication credentials (email and password)
+	 */
+	constructor(
+		urls: UrlConfig | string,
+		private readonly credentials: Credentials,
+	) {
+		if (typeof urls === "string") {
+			// When a string is provided, treat it as the 'base' property
+			urls = this.inferUrls(urls);
+		}
+		this.urls = urls;
+		this.wroomClient = new WroomClient(this.urls.baseURL, this.credentials);
+		this.authClient = createAuthenticationApiClient(
+			this.urls.authenticationApi,
+			this.credentials,
+		);
+	}
+
+	/**
+	 * If the baseURL is prismic.io, assume the other services have the format
+	 * <name>.prismic.io
+	 */
+	private inferUrls(baseURL: string): UrlConfig {
+		const url = new URL(baseURL);
+		const protocol = url.protocol.slice(0, -1); // Remove the trailing colon from the protocol
+
+		return {
+			baseURL: baseURL,
+			authenticationApi: `${protocol}://auth.${url.hostname}`,
+			customTypesApi: `${protocol}://customtypes.${url.hostname}`,
+		};
+	}
+
+	/**
+	 * Generate a user token from the authentication service.
+	 *
+	 * @returns a JWT token
+	 */
+	async getUserApiToken(): Promise<string> {
+		return this.authClient.getToken();
+	}
+
+	/**
+	 * Create a new repository in Wroom.
+	 *
+	 * @param repositoryName - The name of the repository.
+	 *
+	 * @throws Error if the repository creation fails.
+	 */
+	async createRepository(
+		config: {
+			prefix?: string;
+		} & RepositoryConfig = {},
+	): Promise<RepositoryManager> {
+		const profiler = logger.startTimer();
+
+		const { prefix = "e2e-tests" } = config;
+		const repositoryName = `${prefix}-${randomString()}`;
+
+		const response = await this.wroomClient.post(
+			null,
+			"/authentication/newrepository",
+			{
+				domain: repositoryName,
+				framework: "next",
+				plan: "personal",
+				isAnnual: "false",
+				role: "developer",
+			},
+		);
+		if (response.status !== 200) {
+			logHttpResponse(response);
+			throw new Error(`Could not create repository ${repositoryName}`);
+		}
+		this.repositories.add(repositoryName);
+
+		profiler.done({ message: `created repository '${repositoryName}'` });
+
+		const repository = this.getRepositoryManager(repositoryName);
+		await repository.configure(config);
+
+		return repository;
+	}
+
+	/**
+	 * Delete a repository from Wroom.
+	 *
+	 * @param repository - The name of the repository.
+	 *
+	 * @throws Error if the repository deletion fails.
+	 */
+	async deleteRepository(repository: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			repository,
+			"./app/settings/delete",
+			{ confirm: repository, password: this.credentials.password },
+		);
+		if (response.status !== 200) {
+			logHttpResponse(response);
+			throw new Error(`Could not delete repository ${repository}`);
+		}
+		this.repositories.remove(repository);
+		profiler.done({ message: `deleted repository '${repository}'` });
+	}
+
+	/**
+	 * Cleanup test data. For example, it deletes repositories created using
+	 * createRepository()
+	 */
+	async tearDown(): Promise<void> {
+		const repositories = this.repositories.getAll();
+		for (const repository of repositories) {
+			await this.deleteRepository(repository);
+		}
+	}
+
+	/**
+	 * Return a repository utilities object for a repository.
+	 *
+	 * @param name - The name of the repository.
+	 */
+	getRepositoryManager(name: string): RepositoryManager {
+		const customTypeClient = createCustomTypesApiClient(
+			this.urls.customTypesApi,
+			name,
+			this.authClient,
+		);
+
+		return new RepositoryManager(name, this.wroomClient, customTypeClient);
+	}
+}
+
+export type UrlConfig = {
+	/** Prismic base url */
+	baseURL: string;
+	/** Custom types api base url */
+	customTypesApi: string;
+	/** Auth service api base url */
+	authenticationApi: string;
+};

package/src/managers/repository.ts

@@ -0,0 +1,277 @@
+import { AxiosResponse } from "axios";
+
+import {
+	CustomType,
+	SharedSlice,
+} from "@prismicio/types-internal/lib/customtypes";
+
+import { CustomTypesClient } from "../clients/customTypesApi";
+import { WroomClient } from "../clients/wroom";
+import { logHttpResponse, logger } from "../utils/log";
+
+/** Utility to manage test data for a Prismic repository */
+export class RepositoryManager {
+	constructor(
+		readonly name: string,
+		private readonly wroomClient: WroomClient,
+		private readonly customTypesApiClient: CustomTypesClient,
+	) {}
+
+	async configure(config: RepositoryConfig): Promise<void> {
+		if (config.locales) {
+			await this.createLocales(config.locales);
+		}
+
+		if (config.customLocale) {
+			await this.createCustomLocale(config.customLocale);
+		}
+
+		if (config.defaultLocale) {
+			await this.setDefaultLocale(config.defaultLocale);
+		}
+
+		if (config.slices) {
+			await this.createSlices(config.slices);
+		}
+
+		if (config.customTypes) {
+			await this.createCustomTypes(config.customTypes);
+		}
+
+		if (config.preview) {
+			await this.createPreview(config.preview);
+		}
+	}
+	/** @returns the repository base url, like https://my-repo.prismic.io */
+	getBaseURL(): string {
+		const url = new URL(this.wroomClient.getBaseURL());
+		url.hostname = `${this.name}.${url.hostname}`;
+
+		return url.toString();
+	}
+
+	/**
+	 * Set additional standard locales for a repository in Wroom, does not fail if
+	 * the locales already exist.
+	 *
+	 * @param locales - An array of all locales to be added to the repository.
+	 *
+	 * @throws Error if setting the locales fails.
+	 */
+	async createLocales(locales: string[]): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			"app/settings/multilanguages",
+			{ languages: locales },
+		);
+
+		const { data, status } = response;
+		const success =
+			status === 200 ||
+			(status === 400 &&
+				(data as string).includes("already existing languages"));
+		if (!success) {
+			logHttpResponse(response);
+			throw new Error(`Could not add locales ${locales.join(", ")}`);
+		}
+		profiler.done({ message: `standard locales '${locales}' set` });
+	}
+
+	/**
+	 * Set additional custom locale for a repository in Wroom, does not fail if
+	 * the locales already exist.
+	 *
+	 * @param locale - The locale to be added to the repository.
+	 *
+	 * @throws Error if setting the locale fails.
+	 */
+	async createCustomLocale(locale: CustomLocale): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			"app/settings/multilanguages/custom",
+			locale,
+		);
+
+		const { data, status } = response;
+		const success =
+			status === 200 ||
+			(status === 400 && (data as string).includes("code is already used"));
+		if (!success) {
+			logHttpResponse(response);
+			throw new Error(`Could not create custom locale ${locale}`);
+		}
+		profiler.done({
+			message: `custom locale ${JSON.stringify(locale)} created`,
+		});
+	}
+
+	private failIfNot200(response: AxiosResponse, msg: string) {
+		if (response.status !== 200) {
+			logHttpResponse(response);
+			throw new Error(msg);
+		}
+	}
+
+	/**
+	 * Delete a locale from a repository.
+	 *
+	 * @param locale - locale to remove from the repository configuration.
+	 *
+	 * @throws Error if deleting the locale fails.
+	 */
+	async deleteLocale(locale: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			`app/settings/multilanguages/${locale}/delete`,
+		);
+		this.failIfNot200(response, `Could not delete locale ${locale}`);
+		profiler.done({ message: `locale '${locale}' deleted` });
+	}
+
+	/**
+	 * Set the default (master) locale for a repository in Wroom, the locale needs
+	 * to exist for the repository.
+	 *
+	 * @param locale - The locale to be set as the default.
+	 *
+	 * @throws Error if setting the default locale fails.
+	 */
+	async setDefaultLocale(locale: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			`/app/settings/multilanguages/${locale}/defineAsMaster`,
+		);
+
+		this.failIfNot200(response, `Could not set default locale to ${locale}`);
+		profiler.done({ message: `default locale set to '${locale}'` });
+	}
+
+	/**
+	 * Creates a release.
+	 *
+	 * @param label - The label for the release.
+	 *
+	 * @returns A Promise that resolves when the release is created.
+	 */
+	async createRelease(label: string): Promise<{ id: string }> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(this.name, "./app/releases", {
+			label,
+		});
+		this.failIfNot200(response, `Could not create release ${label}`);
+		profiler.done({ message: `release '${label}' created` });
+
+		return response.data;
+	}
+
+	/**
+	 * Deletes a repository release.
+	 *
+	 * @param repository - The name of the repository.
+	 * @param id - The ID of the release to be deleted.
+	 */
+	async deleteRelease(id: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			`./app/releases/${id}/delete`,
+			{},
+		);
+
+		this.failIfNot200(response, `Could not delete release with id ${id}`);
+		profiler.done({ message: `release '${id}' deleted` });
+	}
+
+	/**
+	 * Creates a preview for a repository.
+	 *
+	 * @param data - The data for creating the preview.
+	 */
+	async createPreview(data: Preview): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			`./previews/new`,
+			data,
+		);
+
+		this.failIfNot200(response, `Could not create preview ${data.name}`);
+		profiler.done({ message: `preview '${data.name}' created` });
+
+		return response.data;
+	}
+
+	/**
+	 * Deletes a preview from a repository.
+	 *
+	 * @param id - The ID of the preview to be deleted.
+	 */
+	async deletePreview(id: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.wroomClient.post(
+			this.name,
+			`./previews/delete/${id}`,
+			{},
+		);
+
+		this.failIfNot200(response, `Could not delete preview with id${id}`);
+		profiler.done({ message: `preview '${id}' deleted` });
+	}
+
+	/**
+	 * Create Custom Types using the Custom types api.
+	 *
+	 * @param customTypes -
+	 */
+	async createCustomTypes(customTypes: CustomType[]): Promise<void> {
+		await this.customTypesApiClient.createCustomTypes(customTypes);
+	}
+
+	/**
+	 * Create slices using the Custom types api.
+	 *
+	 * @param slices -
+	 */
+	async createSlices(slices: SharedSlice[]): Promise<void> {
+		await this.customTypesApiClient.createSlices(slices);
+	}
+}
+
+export type RepositoryConfig = {
+	customLocale?: CustomLocale;
+	locales?: string[];
+	defaultLocale?: string;
+	slices?: SharedSlice[];
+	customTypes?: CustomType[];
+	preview?: Preview;
+};
+
+export type Preview = {
+	name: string;
+	websiteURL: string;
+	resolverPath: string;
+};
+
+export type CustomLocale = {
+	lang: {
+		label: string;
+		id: string;
+		useStandardAnalyzer?: boolean;
+	};
+	region: {
+		label: string;
+		id: string;
+	};
+};

package/src/types.ts

@@ -0,0 +1 @@
+export type Credentials = { email: string; password: string };

package/src/utils/cookies.ts

@@ -0,0 +1,30 @@
+import { AxiosHeaderValue } from "axios";
+
+/**
+ * Extract the value of a specific cookie from Axios cookies.
+ *
+ * @param cookies - Axios cookies, can be a string or an array
+ * @param cookieName - The name of the cookie to extract.
+ */
+export const extractCookie = (
+	cookies: AxiosHeaderValue | undefined,
+	cookieName: string,
+): string | undefined => {
+	const regex = new RegExp(`${cookieName}=([^;]+)`, "i"); // 'i' flag for case-insensitivity
+
+	if (typeof cookies === "string") {
+		const match = cookies.match(regex);
+
+		return match ? match[1] : undefined;
+	}
+	if (cookies instanceof Array) {
+		for (const cookie of cookies) {
+			const match = cookie.match(regex);
+			if (match) {
+				return match[1];
+			}
+		}
+	}
+
+	return undefined;
+};

package/src/utils/envVariableManager.ts

@@ -0,0 +1,35 @@
+/**
+ * Manage a list of strings within an environment variable. This is useful to
+ * share data across different test phases (setup, teardown, test execution) as
+ * most test frameworks run these in independent states
+ */
+export class EnvVariableManager {
+	constructor(private variableName: string) {}
+
+	/** add a string and persist it in the environment variable */
+	add(value: string): void {
+		const existingValues = this.getAll();
+		existingValues.push(value);
+
+		this.setAll(existingValues);
+	}
+
+	/** remove a string from the environment variable */
+	remove(value: string): void {
+		const existingValues = this.getAll();
+		const updatedValues = existingValues.filter((item) => item !== value);
+
+		this.setAll(updatedValues);
+	}
+
+	/** return all items stored in the environment variable */
+	getAll(): string[] {
+		const value = process.env[this.variableName] || "[]";
+
+		return JSON.parse(value);
+	}
+
+	private setAll(values: string[]): void {
+		process.env[this.variableName] = JSON.stringify(values);
+	}
+}

package/src/utils/log.ts

@@ -0,0 +1,26 @@
+import { AxiosResponse } from "axios";
+import { createLogger, format, transports } from "winston";
+
+export const logHttpResponse = (response: AxiosResponse): void => {
+	const { status, data } = response;
+	const { url = "" } = response.config;
+	logger.info(`Call to ${url} failed, received [${status}] ${data}`);
+};
+
+const { combine, printf } = format;
+
+const customFormat = printf(({ message, durationMs }) => {
+	const baseMsg = `[test data] ${message}`;
+	if (durationMs) {
+		return `${baseMsg} in ${durationMs}ms`;
+	}
+
+	return baseMsg;
+});
+
+export const logger = createLogger({
+	silent: process.env["prismic_e2e_tests_utils_silent"] === "true",
+	level: process.env["prismic_e2e_tests_utils_log_level"] || "info",
+	format: combine(customFormat),
+	transports: [new transports.Console()],
+});

package/src/utils/random.ts

@@ -0,0 +1,14 @@
+import { createHash } from "crypto";
+
+/**
+ * Generate a random string
+ *
+ * @param length - max 32
+ *
+ * @returns
+ */
+export const randomString = (length = 16): string => {
+	const uniqueInput = Math.random().toString();
+
+	return createHash("md5").update(uniqueInput).digest("hex").slice(0, length);
+};