@prismicio/e2e-tests-utils 1.3.0 → 1.3.2

package/src/clients/contentApi.ts

@@ -0,0 +1,235 @@
+import { APIResponse, request } from "@playwright/test";
+
+export interface ContentApiError {
+	type: string;
+	message: string;
+}
+export interface ContentApiSearchResponse {
+	page: number;
+	results_per_page: number;
+	results_size: number;
+	total_results_size: number;
+	total_pages: number;
+	next_page: string | null;
+	prev_page: string | null;
+	results: ContentApiDocument[];
+}
+
+export interface ContentApiDocument {
+	id: string;
+	uid: string | null;
+	url: string | null;
+	type: string;
+	href: string;
+	tags: string[];
+	first_publication_date: string;
+	last_publication_date: string;
+	slugs: string[];
+	linked_documents: unknown[];
+	lang: string;
+	alternate_languages: string[];
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	data: Record<string, any>;
+}
+
+export interface ContentApiGraphQLResponse {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	data: Record<string, any>;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	errors?: { message: string; locations: any }[];
+}
+
+export interface ContentApiRef {
+	id: string;
+	ref: string;
+	label: string;
+	isMasterRef?: boolean;
+}
+
+interface ContentApiRepoConfigResponse {
+	refs: ContentApiRef[];
+	bookmarks: Record<string, unknown>;
+	types: Record<string, string>;
+	languages: {
+		id: string;
+		name: string;
+		is_master: boolean;
+	}[];
+	oauth_initiate: string;
+	oauth_token: string;
+	tags: string[];
+	license: string;
+	version: string;
+}
+
+type SearchQueryParams = {
+	ref?: string;
+	query?: string;
+	q?: string;
+	graphQuery?: string;
+	fetchLinks?: string;
+	orderings?: string;
+	pageSize?: number;
+	page?: number;
+	lang?: string;
+	after?: string;
+	routes?: string;
+};
+
+type ApiVersions = "v1" | "v2";
+
+/**
+ * Client to query the Prismic content api. Uses Playwright to benefit from
+ * network request traces in your reports. The @prismicio/client package could
+ * have been used but had too many abstractions (caching, error handling) that
+ * we didn't want for test execution. See api docs:
+ * https://prismic.io/docs/rest-api-technical-reference
+ */
+export class ContentApiClient {
+	#version: ApiVersions;
+	#accessToken: string | undefined;
+
+	/**
+	 * @example To instantiate the class:
+	 *
+	 * ```js
+	 * new ContentApiClient("https://my-repo.cdn.prismic.io", {
+	 * 	version: "v2",
+	 * 	accessToken: "my-secret-token",
+	 * });
+	 * ```
+	 *
+	 * @param baseURL - the api base URL like https://my-repo.cdn.prismic.io
+	 * @param config - Optional configuration
+	 *
+	 *   - {@link config.version}: Api version, default is "v2"
+	 *   - {@link config.accessToken}: Access token for the content api -
+	 *       https://prismic.io/docs/access-token
+	 */
+	constructor(
+		private readonly baseURL: string,
+		config: { version?: ApiVersions; accessToken?: string } = {},
+	) {
+		this.#version = config.version || "v2";
+		this.#accessToken = config.accessToken;
+	}
+
+	#context() {
+		return request.newContext({
+			baseURL: this.baseURL,
+			// reset any Authorization header set globally with Playwright
+			// didn't find a way to delete it
+			extraHTTPHeaders: { Authorization: "" },
+		});
+	}
+
+	async get(
+		path: string,
+		params?: SearchQueryParams,
+		headers?: Record<string, string>,
+	): Promise<APIResponse> {
+		const context = await this.#context();
+		const securityParams = {
+			...(this.#accessToken ? { access_token: this.#accessToken } : {}),
+		};
+
+		return context.get(path, {
+			params: { ...securityParams, ...params },
+			headers,
+		});
+	}
+
+	async getAsJson<T>(
+		url: string,
+		params?: SearchQueryParams,
+		headers?: Record<string, string>,
+	): Promise<T> {
+		const response = await this.get(url, params, headers);
+
+		return response.json() as T;
+	}
+
+	/** Query the graphql api - https://prismic.io/docs/graphql-technical-reference */
+	async graphql(
+		ref: string,
+		query: string,
+	): Promise<ContentApiGraphQLResponse> {
+		return this.getAsJson<ContentApiGraphQLResponse>(
+			"/graphql",
+			{ query },
+			{ "Prismic-ref": ref },
+		);
+	}
+
+	async getRefs(): Promise<ContentApiRef[]> {
+		const data = await this.getAsJson<ContentApiRepoConfigResponse>(
+			`/api/${this.#version}`,
+		);
+
+		return data.refs;
+	}
+
+	async getMasterRef(): Promise<string> {
+		const refs = await this.getRefs();
+
+		const masterRef = refs.find(({ isMasterRef }) => isMasterRef === true);
+		if (!masterRef) {
+			throw "No master ref found";
+		}
+
+		return masterRef.ref;
+	}
+
+	async getRefByReleaseID(releaseID: string): Promise<string> {
+		const refs = await this.getRefs();
+		const release = refs.find(({ id }) => id === releaseID);
+		if (!release) {
+			throw `No ref found for release ${releaseID}`;
+		}
+
+		return release.ref;
+	}
+
+	/** Search documents from the `/api/v<version>/documents/search` endpoint. */
+	async search(filters?: SearchQueryParams): Promise<ContentApiSearchResponse> {
+		let ref = filters?.ref;
+		if (!ref) {
+			ref = await this.getMasterRef();
+		}
+
+		return this.getAsJson<ContentApiSearchResponse>(
+			`/api/${this.#version}/documents/search`,
+			{
+				...filters,
+				ref,
+			},
+		);
+	}
+
+	/**
+	 * Search for a single document by its it, using the
+	 * `/api/v<version>/documents/search` endpoint and a default filter.
+	 */
+	async searchByID(
+		id: string,
+		filters?: SearchQueryParams,
+	): Promise<ContentApiSearchResponse> {
+		return this.search({ ...filters, q: `[[at(document.id, "${id}")]]` });
+	}
+
+	/** Retrieve a single document or undefined if not found. */
+	async getDocumentByID(
+		id: string,
+		filters?: SearchQueryParams,
+	): Promise<ContentApiDocument | undefined> {
+		const data = await this.searchByID(id, filters);
+		switch (data.results_size) {
+			case 0:
+				return;
+			case 1:
+				return data.results[0];
+			default:
+				throw new Error(`Too many documents returned with the same id ${id}`);
+		}
+	}
+}

package/src/clients/coreApi.ts

@@ -12,6 +12,7 @@ type Language = {
 
 export type CoreClient = {
 	getLanguages(): Promise<Language[]>;
+	publishDraft(documentId: string): Promise<void>;
 };
 
 /** Client for interacting with the core API */
@@ -41,7 +42,7 @@ export const createCoreApiClient = (
 			"core/repository",
 		);
 
-		if (![200].includes(result.status) || !result.data.languages) {
+		if (200 !== result.status || !result.data.languages) {
 			logHttpResponse(result);
 			throw new Error("Could not get languages from the core api.");
 		}
@@ -51,7 +52,19 @@ export const createCoreApiClient = (
 		return result.data.languages;
 	}
 
+	async function publishDraft(documentId: string): Promise<void> {
+		const result = await client.patch(`core/documents/${documentId}/draft`, {
+			status: "published",
+		});
+
+		if (204 !== result.status) {
+			logHttpResponse(result);
+			throw new Error(`Could not publish document with id ${documentId}`);
+		}
+	}
+
 	return {
 		getLanguages,
+		publishDraft,
 	};
 };

package/src/clients/migrationApi.ts

@@ -0,0 +1,72 @@
+import axios, { AxiosInstance } from "axios";
+
+import { logHttpResponse } from "../utils/log";
+
+import { AuthenticationClient } from "./authenticationApi";
+
+export type MigrationClient = {
+	createDocument(data: DocumentPayload): Promise<DocumentResponse>;
+};
+
+export type DocumentPayload = {
+	uid?: string | null;
+	type: string;
+	lang: string;
+	title: string;
+	tags?: string[];
+	alternate_language_id?: string;
+	data: Record<string, unknown>;
+	// if true, the document will be part of the documents list instead of in the migration release
+	inDocuments?: boolean;
+};
+
+export type DocumentResponse = {
+	id: string;
+	type: string;
+	lang: string;
+	title: string;
+	uid?: string;
+};
+
+export const createMigrationApiClient = (
+	baseURL: string,
+	repository: string,
+	authClient: AuthenticationClient,
+): MigrationClient => {
+	const client: AxiosInstance = axios.create({
+		baseURL,
+		headers: {
+			repository,
+		},
+		validateStatus: () => true, // Don't throw on 4XX errors
+	});
+
+	// Add an interceptor to authenticate requests
+	client.interceptors.request.use(async (config) => {
+		const auth = "Authorization";
+		if (!config.headers[auth]) {
+			const token = await authClient.getToken();
+			config.headers[auth] = `Bearer ${token}`;
+		}
+		config.headers["repository"] = repository;
+
+		return config;
+	});
+
+	async function createDocument(
+		data: DocumentPayload,
+	): Promise<DocumentResponse> {
+		const result = await client.post<DocumentResponse>("/documents", data);
+
+		if (201 !== result.status) {
+			logHttpResponse(result);
+			throw new Error("Could not create a document with the migration api.");
+		}
+
+		return result.data;
+	}
+
+	return {
+		createDocument,
+	};
+};

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from "./managers/repositories";
 export * from "./managers/repository";
+export * from "./clients/contentApi";
+export * from "./clients/migrationApi";
 export * from "./types";

package/src/managers/repositories.ts

@@ -7,6 +7,7 @@ import {
 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";
@@ -91,6 +92,7 @@ export class RepositoriesManager {
 			baseURL: baseURL,
 			authenticationApi: `${protocol}://auth.${url.hostname}`,
 			customTypesApi: `${protocol}://customtypes.${url.hostname}`,
+			migrationApi: `${protocol}://migration.${url.hostname}`,
 		};
 	}
 
@@ -191,13 +193,17 @@ export class RepositoriesManager {
 	 * @param name - The name of the repository.
 	 */
 	getRepositoryManager(name: string): RepositoryManager {
+		const { urlConfig } = this.config;
 		const customTypeClient = createCustomTypesApiClient(
-			this.config.urlConfig.customTypesApi,
+			urlConfig.customTypesApi,
 			name,
 			this.authClient,
 		);
-		const coreApiUrl = getRepositoryUrl(this.config.urlConfig.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,
@@ -205,6 +211,7 @@ export class RepositoriesManager {
 			this.authClient,
 			this.wroomClient,
 			customTypeClient,
+			migrationApiClient,
 			this.manageV2Client,
 		);
 	}

package/src/managers/repository.ts

@@ -1,3 +1,4 @@
+import { expect } from "@playwright/test";
 import { AxiosResponse } from "axios";
 
 import {
@@ -6,9 +7,15 @@ import {
 } 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";
@@ -21,6 +28,7 @@ export class RepositoryManager {
 		private readonly authApiClient: AuthenticationClient,
 		private readonly wroomClient: WroomClient,
 		private readonly customTypesApiClient: CustomTypesClient,
+		private readonly migrationApiClient: MigrationClient | undefined,
 		private readonly manageV2Client: ManageV2Client,
 	) {}
 
@@ -74,11 +82,29 @@ export class RepositoryManager {
 			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.
@@ -499,6 +525,50 @@ export class RepositoryManager {
 			} 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({
+			inDocuments: true,
+			...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,
+		});
+
+		return result;
+	}
 }
 
 export type RepositoryConfig = {

package/src/types.ts

@@ -5,6 +5,8 @@ export type UrlConfig = {
 	customTypesApi: string;
 	/** Auth service api base url */
 	authenticationApi: string;
+	/** Prismic migration api base url */
+	migrationApi?: string;
 };
 
 export type AuthConfig = {