@prismicio/e2e-tests-utils 1.2.0 → 1.3.1

package/src/managers/repositories.ts

@@ -1,4 +1,4 @@
-import { Credentials } from "../types";
+import { SetupConfiguration, UrlConfig } from "../types";
 
 import {
 	AuthenticationClient,
@@ -6,6 +6,8 @@ import {
 } from "../clients/authenticationApi";
 import { createCoreApiClient } from "../clients/coreApi";
 import { createCustomTypesApiClient } from "../clients/customTypesApi";
+import { ManageV2Client } from "../clients/manageV2";
+import { createMigrationApiClient } from "../clients/migrationApi";
 import { WroomClient } from "../clients/wroom";
 import { EnvVariableManager } from "../utils/envVariableManager";
 import { logHttpResponse, logger } from "../utils/log";
@@ -18,30 +20,29 @@ import { RepositoryConfig, RepositoryManager } from "./repository";
  * Factory method to create a RepositoriesManager to manage repositories test
  * data.
  *
- * @param urlConfig - If provided as an object:
+ * @param configuration - Global object containing the different configurations
+ *   required to setup the RepositoriesManager.
  *
- *       - {@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
+ *       - {@link configuration.urlConfig}: Configuration around the API's URLs management.
+ *       - {@link configuration.authConfig}: Configuration around the authentication of a user.
+ *       - {@link configuration.manageV2Config}: Optional Configuration used to make calls to ManageV2.
  *
  * @returns An instance of {@link RepositoriesManager} to manage test data.
  */
 export const createRepositoriesManager = (
-	urlConfig: UrlConfig | string,
-	auth: Credentials,
+	configuration: SetupConfiguration,
 ): RepositoriesManager => {
-	return new RepositoriesManager(urlConfig, auth);
+	return new RepositoriesManager(configuration);
 };
 
 /** Utility object to manage Prismic test data */
 export class RepositoriesManager {
-	private readonly urls: UrlConfig;
+	private readonly config: Omit<SetupConfiguration, "urlConfig"> & {
+		urlConfig: UrlConfig;
+	};
 	private readonly wroomClient: WroomClient;
 	private readonly authClient: AuthenticationClient;
+	private readonly manageV2Client: ManageV2Client;
 	/**
 	 * helper to keep track of repositories across independent test phases (setup,
 	 * teardown)
@@ -51,22 +52,31 @@ export class RepositoriesManager {
 	);
 
 	/**
-	 * @param urlConfig - The base URL of the Wroom app.
+	 * @param configuration - Global object containing the different configuration
+	 *   required to setup the different clients.
 	 * @param credentials - Authentication credentials (email and password)
 	 */
-	constructor(
-		urlConfig: UrlConfig | string,
-		private readonly credentials: Credentials,
-	) {
-		if (typeof urlConfig === "string") {
+	constructor(configuration: SetupConfiguration) {
+		this.config = {
+			...configuration,
 			// When a string is provided, treat it as the 'base' property
-			urlConfig = this.inferUrls(urlConfig);
-		}
-		this.urls = urlConfig;
-		this.wroomClient = new WroomClient(this.urls.baseURL, this.credentials);
+			urlConfig:
+				typeof configuration.urlConfig === "string"
+					? this.inferUrls(configuration.urlConfig)
+					: configuration.urlConfig,
+		};
+
+		this.wroomClient = new WroomClient(
+			this.config.urlConfig.baseURL,
+			this.config.authConfig,
+		);
 		this.authClient = createAuthenticationApiClient(
-			this.urls.authenticationApi,
-			this.credentials,
+			this.config.urlConfig.authenticationApi,
+			this.config.authConfig,
+		);
+		this.manageV2Client = new ManageV2Client(
+			this.config.urlConfig.baseURL,
+			this.config.manageV2Config,
 		);
 	}
 
@@ -82,6 +92,7 @@ export class RepositoriesManager {
 			baseURL: baseURL,
 			authenticationApi: `${protocol}://auth.${url.hostname}`,
 			customTypesApi: `${protocol}://customtypes.${url.hostname}`,
+			migrationApi: `${protocol}://migration.${url.hostname}`,
 		};
 	}
 
@@ -149,7 +160,7 @@ export class RepositoriesManager {
 		const post = async () =>
 			this.wroomClient.post(repository, "app/settings/delete", {
 				confirm: repository,
-				password: this.credentials.password,
+				password: this.config.authConfig.password,
 			});
 		const response = await post();
 		if (response.status !== 200) {
@@ -182,28 +193,26 @@ export class RepositoriesManager {
 	 * @param name - The name of the repository.
 	 */
 	getRepositoryManager(name: string): RepositoryManager {
+		const { urlConfig } = this.config;
 		const customTypeClient = createCustomTypesApiClient(
-			this.urls.customTypesApi,
+			urlConfig.customTypesApi,
 			name,
 			this.authClient,
 		);
-		const coreApiUrl = getRepositoryUrl(this.urls.baseURL, name);
+		const coreApiUrl = getRepositoryUrl(urlConfig.baseURL, name);
 		const coreApiClient = createCoreApiClient(coreApiUrl, this.authClient);
+		const migrationApiClient = urlConfig.migrationApi
+			? createMigrationApiClient(urlConfig.migrationApi, name, this.authClient)
+			: undefined;
 
 		return new RepositoryManager(
 			name,
 			coreApiClient,
+			this.authClient,
 			this.wroomClient,
 			customTypeClient,
+			migrationApiClient,
+			this.manageV2Client,
 		);
 	}
 }
-
-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

@@ -1,3 +1,4 @@
+import { expect } from "@playwright/test";
 import { AxiosResponse } from "axios";
 
 import {
@@ -5,8 +6,16 @@ import {
 	SharedSlice,
 } from "@prismicio/types-internal/lib/customtypes";
 
+import type { AuthenticationClient } from "../clients/authenticationApi";
+import { ContentApiClient } from "../clients/contentApi";
 import type { CoreClient } from "../clients/coreApi";
 import { CustomTypesClient } from "../clients/customTypesApi";
+import { ManageV2Client } from "../clients/manageV2";
+import {
+	DocumentPayload,
+	DocumentResponse,
+	MigrationClient,
+} from "../clients/migrationApi";
 import { WroomClient } from "../clients/wroom";
 import { logHttpResponse, logger } from "../utils/log";
 import { getRepositoryUrl } from "../utils/urls";
@@ -16,8 +25,11 @@ export class RepositoryManager {
 	constructor(
 		readonly name: string,
 		private readonly coreApiClient: CoreClient,
+		private readonly authApiClient: AuthenticationClient,
 		private readonly wroomClient: WroomClient,
 		private readonly customTypesApiClient: CustomTypesClient,
+		private readonly migrationApiClient: MigrationClient | undefined,
+		private readonly manageV2Client: ManageV2Client,
 	) {}
 
 	async configure(config: RepositoryConfig): Promise<void> {
@@ -65,12 +77,34 @@ export class RepositoryManager {
 		if (config.preview) {
 			await this.createPreview(config.preview);
 		}
+
+		if (config.rolePerLocal) {
+			await this.toggleRolePerLocal(true);
+		}
 	}
+
 	/** @returns the repository base url, like https://my-repo.prismic.io */
 	getBaseURL(): string {
 		return getRepositoryUrl(this.wroomClient.getBaseURL(), this.name);
 	}
 
+	/** @returns the repository base cdn url, like https://my-repo.cdn.prismic.io */
+	getBaseCdnURL(): string {
+		return getRepositoryUrl(this.wroomClient.getBaseURL(), `${this.name}.cdn`);
+	}
+
+	/**
+	 * @returns a Content Type api client configured to target the repository CDN
+	 *   url. Uses Playwright for requests so if your project uses Playwright too,
+	 *   any network request will be present in Playwright test reports.
+	 */
+	getContentApiClient(config?: {
+		version?: "v1" | "v2";
+		accessToken?: string;
+	}): ContentApiClient {
+		return new ContentApiClient(this.getBaseCdnURL(), config);
+	}
+
 	/**
 	 * Set additional standard locales for a repository in Wroom, does not fail if
 	 * the locales already exist.
@@ -261,118 +295,276 @@ export class RepositoryManager {
 	}
 
 	/**
-	 * Create a webhook.
+	 * 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);
+	}
+
+	/**
+	 * Create an access token to query private items of the Content api.
 	 *
-	 * @returns A Promise that resolves with the webhook id.
+	 * @param appName - mandatory authorized application name
+	 * @param tokenScope - access token scope. Use "master" to when your content
+	 *   api is fully private or "master+releases" to access private releases
 	 */
-	async createWebhook(
-		name: string,
-		url: string,
-		secret: string,
-		triggers: {
-			documentsPublished?: boolean;
-			documentsUnpublished?: boolean;
-			releasesCreated?: boolean;
-			releasesUpdated?: boolean;
-			tagsCreated?: boolean;
-			tagsDeleted?: boolean;
-		},
-		active: boolean,
+	async createContentAPIToken(
+		appName: string,
+		tokenScope: "master" | "master+releases" = "master",
 	): Promise<string> {
 		const profiler = logger.startTimer();
+		type AuthorizedAppResponse = {
+			id: string;
+			name: string;
+			wroom_auths: { token: string; scope: "master" | "master+releases" }[];
+		};
+		const existingApps: AxiosResponse<AuthorizedAppResponse[]> =
+			await this.wroomClient.get(this.name, "settings/security/contentapi");
 
-		const response = await this.wroomClient.post(
-			this.name,
-			"app/settings/webhooks/create",
-			{
-				name,
-				url,
-				secret,
-				active: active ? "on" : "off",
-				...triggers,
-			},
+		this.failIfNot200(
+			existingApps,
+			`Could not get status of existing applications to generate a content api token`,
 		);
-		this.failIfNot200(response, `Could not create webhook ${name}`);
-		profiler.done({ message: `webhook '${name}' created` });
+		let app = existingApps.data.find(({ name, wroom_auths }) => {
+			return name === appName && wroom_auths.length > 0;
+		});
+
+		if (!app) {
+			const response: AxiosResponse<AuthorizedAppResponse> =
+				await this.wroomClient.post(this.name, "settings/security/oauthapp", {
+					app_name: appName,
+				});
+
+			this.failIfNot200(
+				response,
+				`Could not create content api app ${appName}`,
+			);
+			app = response.data;
+		}
+
+		let tokenInfo = app.wroom_auths.find(({ scope }) => scope === tokenScope);
+		if (!tokenInfo) {
+			const response = await this.wroomClient.post(
+				this.name,
+				"settings/security/authorizations",
+				{
+					app: app.id,
+					scope: tokenScope,
+				},
+			);
+			this.failIfNot200(
+				response,
+				`Could not create content api access token for app ${appName} with scope ${tokenScope}`,
+			);
+			tokenInfo = response.data;
+		}
+
+		profiler.done({
+			message: `content api access token for app '${appName}' created`,
+		});
+
+		if (!tokenInfo?.token) {
+			throw `Could not create content api access token for app ${appName} with scope ${tokenScope}`;
+		}
+
+		return tokenInfo.token;
+	}
+
+	/** Create a permanent access token to authenticate to Prismic public apis. */
+	async createPermanentAccessToken(): Promise<string> {
+		const profiler = logger.startTimer();
+
+		const token = await this.authApiClient.getMachine2MachineToken(this.name);
+
+		profiler.done({
+			message: `machine2machine token created`,
+		});
 
-		return response.data.created;
+		return token;
 	}
 
 	/**
-	 * Deletes a webhook.
+	 * Toggle the Role per local feature
 	 *
-	 * @param id - The webhook ID.
+	 * @param enabled - The feature new status
 	 */
-	async deleteWebhook(id: string): Promise<void> {
+	async toggleRolePerLocal(enabled: boolean): Promise<void> {
 		const profiler = logger.startTimer();
 
-		const response = await this.wroomClient.post(
-			this.name,
-			`app/settings/webhooks/${id}/delete`,
-			{},
-		);
+		const response = await this.manageV2Client.toggleRolePerLocal({
+			repository: this.name,
+			enabled: enabled,
+		});
 
-		this.failIfNot200(response, `Could not delete webhook with id ${id}`);
-		profiler.done({ message: `webhook '${id}' deleted` });
+		this.failIfNot200(
+			response,
+			`Could not ${enabled ? "enable" : "disable"} Role per local for ${
+				this.name
+			}`,
+		);
+		profiler.done({
+			message: `Role per local ${enabled ? "enabled" : "disabled"}`,
+		});
 	}
 
 	/**
-	 * Create Custom Types using the Custom types api.
+	 * Change the Repository Plan
 	 *
-	 * @param customTypes -
+	 * @param {string} newPlanId - The Id of the new Plan to apply
 	 */
-	async createCustomTypes(customTypes: CustomType[]): Promise<void> {
-		await this.customTypesApiClient.createCustomTypes(customTypes);
+	async changePlan(newPlanId: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.manageV2Client.changePlan({
+			repository: this.name,
+			newPlanId: newPlanId,
+			bypassManualBilling: true, // For now the library does not support Stripe features
+		});
+
+		this.failIfNot200(response, "Could not change the Repository Plan");
+		profiler.done({
+			message: `Repository Plan changed to ${newPlanId}`,
+		});
 	}
 
 	/**
-	 * Create slices using the Custom types api.
+	 * Add a new user to the repository
 	 *
-	 * @param slices -
+	 * @param {string} email - The email of the user
 	 */
-	async createSlices(slices: SharedSlice[]): Promise<void> {
-		await this.customTypesApiClient.createSlices(slices);
+	async addUser(email: string): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response = await this.manageV2Client.addUserToRepository({
+			repository: this.name,
+			email: email,
+		});
+
+		const { data, status } = response;
+		const success =
+			status === 200 ||
+			(status === 409 &&
+				JSON.stringify(data).includes("already a member of the repo"));
+		if (!success) {
+			logHttpResponse(response);
+			throw new Error(`Could not add a new user ${email} to the repository`);
+		}
+		profiler.done({
+			message: `User ${email} was added to the repository`,
+		});
 	}
 
 	/**
-	 * Create a permanent access token along with an application name
+	 * Remove a user from the repository
 	 *
-	 * @param appName - mandatory authorized application name
+	 * @param {string} email - The email of the user
 	 */
-	async createPermanentAccessToken(appName: string): Promise<string> {
+	async removeUser(email: string): Promise<void> {
 		const profiler = logger.startTimer();
-		type AuthorizedAppResponse = {
-			name: string;
-			wroom_auths: { token: string }[];
-		};
-		const existingApps: AxiosResponse<AuthorizedAppResponse[]> =
-			await this.wroomClient.get(this.name, "settings/security/contentapi");
+
+		const response = await this.manageV2Client.removeUserFromRepository({
+			repository: this.name,
+			email: email,
+		});
 
 		this.failIfNot200(
-			existingApps,
-			`Could not get status of existing applications to generate a permanent token`,
+			response,
+			`Could not remove the user ${email} from the repository`,
 		);
-		const existingApp = existingApps.data.find(({ name, wroom_auths }) => {
-			return name === appName && wroom_auths.length > 0;
+		profiler.done({
+			message: `User ${email} was removed from the repository`,
 		});
-		if (existingApp) {
-			return existingApp.wroom_auths[0].token;
-		}
-		const response: AxiosResponse<AuthorizedAppResponse> =
-			await this.wroomClient.post(this.name, "settings/security/oauthapp", {
-				app_name: appName,
-			});
+	}
+
+	/**
+	 * Update the role of a user in a repository
+	 *
+	 * @param {string} email - The email of the user
+	 * @param {string | Record<string, string>} role - The new Role of the user,
+	 *   either a string for basic workflow or an object such as `{ "lang_id":
+	 *   "Writer" }`
+	 *
+	 *   Example of roles are
+	 *
+	 *   - Administrator
+	 *   - Writer
+	 *   - Contributor
+	 *   - Manager (publisher)
+	 */
+	async updateUserRole(
+		email: string,
+		role: string | Record<string, string>,
+	): Promise<void> {
+		const profiler = logger.startTimer();
+
+		const response =
+			typeof role === "string"
+				? await this.wroomClient.updateRole(this.name, email, role)
+				: await this.wroomClient.updateRolePerLocal(this.name, email, role);
 
 		this.failIfNot200(
 			response,
-			`Could not create permanent access token for app name ${appName}`,
+			`Could not update the ${
+				typeof role === "string" ? "role" : "rolePerLocal"
+			} of the user ${email}`,
 		);
 		profiler.done({
-			message: `permanent access token for app name '${appName}' created`,
+			message: `Updated User's ${
+				typeof role === "string" ? "role" : "rolePerLocal"
+			} for user ${email}`,
+		});
+	}
+
+	/**
+	 * Creates a document using the migration api, see
+	 * https://prismic.io/docs/migration-api-technical-reference
+	 *
+	 * @param {DocumentPayload} document - in the migration api format
+	 * @param {string} status - status of the document, if published, the function
+	 *   will wait for a new content api master ref to be created
+	 *
+	 * @returns
+	 */
+	async createDocument(
+		document: DocumentPayload,
+		status: "draft" | "published",
+	): Promise<DocumentResponse> {
+		if (!this.migrationApiClient) {
+			throw "No client found for the migration api. Did you provide a migration api url in your configuration?";
+		}
+
+		const profiler = logger.startTimer();
+
+		const result = await this.migrationApiClient.createDocument(document);
+		let message = `Document created with id '${result.id}'`;
+		if (status === "published") {
+			const contentApi = this.getContentApiClient();
+			const masterRef = await contentApi.getMasterRef();
+			await this.coreApiClient.publishDraft(result.id);
+			await expect
+				.poll(async () => contentApi.getMasterRef(), {
+					timeout: 10_000,
+					message: "Waiting for new master ref to be available",
+				})
+				.not.toBe(masterRef);
+			message += ", status 'published' and new master ref available";
+		}
+		profiler.done({
+			message,
 		});
 
-		// only return the generated token since there is no need to access more
-		return response.data.wroom_auths[0].token;
+		return result;
 	}
 }
 
@@ -383,6 +575,7 @@ export type RepositoryConfig = {
 	slices?: SharedSlice[];
 	customTypes?: CustomType[];
 	preview?: Preview;
+	rolePerLocal?: boolean;
 };
 
 export type Preview = {

package/src/types.ts

@@ -1 +1,29 @@
-export type Credentials = { email: string; password: string };
+export type UrlConfig = {
+	/** Prismic base url */
+	baseURL: string;
+	/** Custom types api base url */
+	customTypesApi: string;
+	/** Auth service api base url */
+	authenticationApi: string;
+	/** Prismic migration api base url */
+	migrationApi?: string;
+};
+
+export type AuthConfig = {
+	email: string;
+	password: string;
+};
+
+export type ManageV2Config = {
+	secret: string;
+	audience: string;
+};
+
+// Global configuration Object
+export type SetupConfiguration = {
+	// 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.
+	urlConfig: UrlConfig | string;
+	authConfig: AuthConfig;
+	manageV2Config?: ManageV2Config;
+};