@wordpress/e2e-test-utils-playwright 1.47.0 → 1.48.0

package/src/request-utils/posts.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+export interface Post {
+	id: number;
+	content: string;
+	status: 'publish' | 'future' | 'draft' | 'pending' | 'private';
+	link: string;
+}
+
+export interface CreatePostPayload {
+	title?: string;
+	content?: string;
+	status: 'publish' | 'future' | 'draft' | 'pending' | 'private';
+	date?: string;
+	date_gmt: string;
+}
+
+/**
+ * Delete all posts using REST API.
+ *
+ * @param this
+ * @param postType The type of post to delete. Defaults to 'posts'.
+ */
+export async function deleteAllPosts(
+	this: RequestUtils,
+	postType: string = 'posts'
+) {
+	// List all posts.
+	// https://developer.wordpress.org/rest-api/reference/posts/#list-posts
+	const posts = await this.rest< Post[] >( {
+		path: `/wp/v2/${ postType }`,
+		params: {
+			per_page: 100,
+			// All possible statuses.
+			status: 'publish,future,draft,pending,private,trash',
+		},
+	} );
+
+	// Delete all posts one by one.
+	// https://developer.wordpress.org/rest-api/reference/posts/#delete-a-post
+	// "/wp/v2/posts" not yet supports batch requests.
+	await Promise.all(
+		posts.map( ( post ) =>
+			this.rest( {
+				method: 'DELETE',
+				path: `/wp/v2/${ postType }/${ post.id }`,
+				params: {
+					force: true,
+				},
+			} )
+		)
+	);
+}
+
+/**
+ * Creates a new post using the REST API.
+ *
+ * @param this
+ * @param payload Post attributes.
+ */
+export async function createPost(
+	this: RequestUtils,
+	payload: CreatePostPayload
+) {
+	return this.createRecord< Post >( 'posts', { ...payload } );
+}

package/src/request-utils/preferences.ts

@@ -0,0 +1,63 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+/**
+ * Reset user preferences
+ *
+ * @param this Request utils.
+ */
+export async function resetPreferences( this: RequestUtils ) {
+	await this.rest( {
+		path: '/wp/v2/users/me',
+		method: 'PUT',
+		data: {
+			meta: {
+				persisted_preferences: {},
+			},
+		},
+	} );
+}
+
+/**
+ * Set scoped user preferences via the REST API.
+ *
+ * Reads the current persisted preferences, merges the new values under the
+ * given scope, and writes them back.
+ *
+ * @param this        Request utils.
+ * @param scope       The preference scope (e.g. 'core/edit-post').
+ * @param preferences Key/value map of preference names to values.
+ */
+export async function setPreferences(
+	this: RequestUtils,
+	scope: string,
+	preferences: Record< string, any >
+) {
+	const user = await this.rest< {
+		meta: { persisted_preferences: Record< string, any > };
+	} >( {
+		path: '/wp/v2/users/me',
+		method: 'GET',
+		params: { context: 'edit' },
+	} );
+
+	const currentPreferences = user.meta?.persisted_preferences ?? {};
+
+	await this.rest( {
+		path: '/wp/v2/users/me',
+		method: 'PUT',
+		data: {
+			meta: {
+				persisted_preferences: {
+					...currentPreferences,
+					[ scope ]: {
+						...( currentPreferences[ scope ] ?? {} ),
+						...preferences,
+					},
+				},
+			},
+		},
+	} );
+}

package/{build/request-utils/records.js → src/request-utils/records.ts}

@@ -1,6 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRecord = createRecord;
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
 /**
  * Create a new record at the given REST base path.
  *
@@ -13,11 +15,14 @@ exports.createRecord = createRecord;
  * @param restBase REST base, appended to `/wp/v2/`.
  * @param payload  Record attributes.
  */
-async function createRecord(restBase, payload) {
-    return this.rest({
-        method: 'POST',
-        path: `/wp/v2/${restBase}`,
-        data: payload,
-    });
+export async function createRecord< T = unknown >(
+	this: RequestUtils,
+	restBase: string,
+	payload: Record< string, unknown >
+) {
+	return this.rest< T >( {
+		method: 'POST',
+		path: `/wp/v2/${ restBase }`,
+		data: payload,
+	} );
 }
-//# sourceMappingURL=records.js.map

package/src/request-utils/rest.ts

@@ -0,0 +1,222 @@
+/**
+ * External dependencies
+ */
+import * as fs from 'fs/promises';
+import { dirname } from 'path';
+import { expect } from '@playwright/test';
+import type { APIRequestContext } from '@playwright/test';
+
+/**
+ * Internal dependencies
+ */
+import { WP_BASE_URL } from '../config';
+import type { RequestUtils, StorageState } from './index';
+
+function splitRequestsToChunks( requests: BatchRequest[], chunkSize: number ) {
+	const arr = [ ...requests ];
+	const cache = [];
+	while ( arr.length ) {
+		cache.push( arr.splice( 0, chunkSize ) );
+	}
+
+	return cache;
+}
+
+async function getAPIRootURL( request: APIRequestContext ) {
+	// Discover the API root url using link header.
+	// See https://developer.wordpress.org/rest-api/using-the-rest-api/discovery/#link-header
+	const response = await request.head( WP_BASE_URL );
+	const links = response.headers().link;
+	const restLink = links?.match( /<([^>]+)>; rel="https:\/\/api\.w\.org\/"/ );
+
+	if ( ! restLink ) {
+		throw new Error( `Failed to discover REST API endpoint.
+ Link header: ${ links }` );
+	}
+
+	const [ , rootURL ] = restLink;
+
+	return rootURL;
+}
+
+async function setupRest( this: RequestUtils ): Promise< StorageState > {
+	let nonce = '';
+	let rootURL = '';
+
+	// Poll until the REST API is discovered.
+	// See https://github.com/WordPress/gutenberg/issues/61627
+	await expect
+		.poll(
+			async () => {
+				try {
+					[ nonce, rootURL ] = await Promise.all( [
+						this.login(),
+						getAPIRootURL( this.request ),
+					] );
+				} catch ( error ) {
+					// Prints the error if the timeout is reached.
+					return error;
+				}
+
+				return !! ( nonce && rootURL );
+			},
+			{
+				message: 'Failed to setup REST API.',
+				timeout: 60_000, // 1 minute.
+			}
+		)
+		.toBe( true );
+
+	const { cookies } = await this.request.storageState();
+
+	const storageState: StorageState = {
+		cookies,
+		nonce,
+		rootURL,
+	};
+
+	if ( this.storageStatePath ) {
+		await fs.mkdir( dirname( this.storageStatePath ), { recursive: true } );
+		await fs.writeFile(
+			this.storageStatePath,
+			JSON.stringify( storageState ),
+			'utf-8'
+		);
+	}
+
+	this.storageState = storageState;
+
+	return storageState;
+}
+
+type RequestFetchOptions = Exclude<
+	Parameters< APIRequestContext[ 'fetch' ] >[ 1 ],
+	undefined
+>;
+export interface RestOptions extends RequestFetchOptions {
+	path: string;
+}
+
+async function rest< RestResponse = any >(
+	this: RequestUtils,
+	options: RestOptions
+): Promise< RestResponse > {
+	const { path, ...fetchOptions } = options;
+
+	if ( ! path ) {
+		throw new Error( '"path" is required to make a REST call' );
+	}
+
+	if ( ! this.storageState?.nonce || ! this.storageState?.rootURL ) {
+		await this.setupRest();
+	}
+
+	const relativePath = path.startsWith( '/' ) ? path.slice( 1 ) : path;
+
+	const url = this.storageState!.rootURL + relativePath;
+
+	try {
+		const response = await this.request.fetch( url, {
+			...fetchOptions,
+			failOnStatusCode: false,
+			headers: {
+				'X-WP-Nonce': this.storageState!.nonce,
+				...( fetchOptions.headers || {} ),
+			},
+		} );
+		const json: RestResponse = await response.json();
+
+		if ( ! response.ok() ) {
+			throw json;
+		}
+
+		return json;
+	} catch ( error ) {
+		// Nonce in invalid, retry again with a renewed nonce.
+		if (
+			typeof error === 'object' &&
+			error !== null &&
+			Object.prototype.hasOwnProperty.call( error, 'code' ) &&
+			( error as { code: string } ).code === 'rest_cookie_invalid_nonce'
+		) {
+			await this.setupRest();
+
+			return this.rest( options );
+		}
+
+		throw error;
+	}
+}
+
+/**
+ * Get the maximum batch size for the REST API.
+ *
+ * @param this
+ * @param forceRefetch Force revalidate the cached max batch size.
+ */
+async function getMaxBatchSize( this: RequestUtils, forceRefetch = false ) {
+	if ( ! forceRefetch && this.maxBatchSize ) {
+		return this.maxBatchSize;
+	}
+
+	const response = await this.rest< {
+		endpoints: {
+			args: {
+				requests: {
+					maxItems: number;
+				};
+			};
+		}[];
+	} >( {
+		method: 'OPTIONS',
+		path: '/batch/v1',
+	} );
+	this.maxBatchSize = response.endpoints[ 0 ].args.requests.maxItems;
+	return this.maxBatchSize;
+}
+
+export interface BatchRequest {
+	method?: string;
+	path: string;
+	headers?: Record< string, string | string[] >;
+	body?: any;
+}
+
+async function batchRest< BatchResponse >(
+	this: RequestUtils,
+	requests: BatchRequest[]
+): Promise< BatchResponse[] > {
+	const maxBatchSize = await this.getMaxBatchSize();
+
+	if ( requests.length > maxBatchSize ) {
+		const chunks = splitRequestsToChunks( requests, maxBatchSize );
+
+		const chunkResponses = await Promise.all(
+			chunks.map( ( chunkRequests ) =>
+				this.batchRest< BatchResponse >( chunkRequests )
+			)
+		);
+
+		return chunkResponses.flat();
+	}
+
+	const batchResponses = await this.rest< {
+		failed?: string;
+		responses: BatchResponse[];
+	} >( {
+		method: 'POST',
+		path: '/batch/v1',
+		data: {
+			requests,
+			validation: 'require-all-validate',
+		},
+	} );
+
+	if ( batchResponses.failed ) {
+		throw batchResponses;
+	}
+
+	return batchResponses.responses;
+}
+
+export { setupRest, rest, getMaxBatchSize, batchRest };

package/src/request-utils/site-settings.ts

@@ -0,0 +1,58 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+type SiteSettings = {
+	title: string;
+	description: string;
+	url: string;
+	email: string;
+	timezone: string;
+	date_format: string;
+	time_format: string;
+	start_of_week: number;
+	language: string;
+	use_smilies: boolean;
+	default_category: number;
+	default_post_format: string;
+	posts_per_page: number;
+	default_ping_status: 'open' | 'closed';
+	default_comment_status: 'open' | 'closed';
+	show_on_front: 'posts' | 'page';
+	page_on_front: number;
+	page_for_posts: number;
+};
+
+/**
+ * Get the site settings.
+ *
+ * @see https://developer.wordpress.org/rest-api/reference/settings/#retrieve-a-site-setting
+ *
+ * @param this RequestUtils.
+ */
+export async function getSiteSettings( this: RequestUtils ) {
+	return await this.rest< SiteSettings >( {
+		path: '/wp/v2/settings',
+		method: 'GET',
+	} );
+}
+
+/**
+ * Update the site settings.
+ *
+ * @see https://developer.wordpress.org/rest-api/reference/settings/#update-a-site-setting
+ *
+ * @param this         RequestUtils.
+ * @param siteSettings The partial settings payload to update.
+ */
+export async function updateSiteSettings(
+	this: RequestUtils,
+	siteSettings: Partial< SiteSettings >
+) {
+	return await this.rest< SiteSettings >( {
+		path: '/wp/v2/settings',
+		method: 'POST',
+		data: siteSettings,
+	} );
+}

package/src/request-utils/templates.ts

@@ -0,0 +1,83 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+
+type TemplateType = 'wp_template' | 'wp_template_part';
+
+interface Template {
+	wp_id: number;
+	id: string;
+}
+
+interface CreateTemplatePayload {
+	slug: string;
+	title?: string;
+	content?: string;
+	description?: string;
+}
+
+const PATH_MAPPING = {
+	wp_template: '/wp/v2/templates',
+	wp_template_part: '/wp/v2/template-parts',
+};
+
+/**
+ * Delete all the templates of given type.
+ *
+ * @param this
+ * @param type - Template type to delete.
+ */
+async function deleteAllTemplates( this: RequestUtils, type: TemplateType ) {
+	const path = PATH_MAPPING[ type ];
+
+	if ( ! path ) {
+		throw new Error( `Unsupported template type: ${ type }.` );
+	}
+
+	const templates = await this.rest< Template[] >( { path } );
+
+	for ( const template of templates ) {
+		if ( ! template?.id || ! template?.wp_id ) {
+			continue;
+		}
+
+		try {
+			await this.rest( {
+				method: 'DELETE',
+				path: `${ path }/${ template.id }`,
+				params: { force: true },
+			} );
+		} catch ( responseError ) {
+			// Disable reason - the error provides valuable feedback about issues with tests.
+			// eslint-disable-next-line no-console
+			console.warn(
+				`deleteAllTemplates failed to delete template (id: ${ template.wp_id }) with the following error`,
+				responseError
+			);
+		}
+	}
+}
+
+/**
+ * Creates a new template using the REST API.
+ *
+ * @param this
+ * @param type    Template type to delete.
+ * @param payload Template attributes.
+ */
+async function createTemplate(
+	this: RequestUtils,
+	type: TemplateType,
+	payload: CreateTemplatePayload
+) {
+	const template = await this.rest< Template >( {
+		method: 'POST',
+		path: PATH_MAPPING[ type ],
+		params: { ...payload, type, status: 'publish', is_wp_suggestion: true },
+	} );
+
+	return template;
+}
+
+export { deleteAllTemplates, createTemplate };

package/src/request-utils/themes.ts

@@ -0,0 +1,110 @@
+/**
+ * Internal dependencies
+ */
+import type { RequestUtils } from './index';
+import { WP_BASE_URL } from '../config';
+
+const THEMES_URL = new URL( 'wp-admin/themes.php', WP_BASE_URL ).href;
+
+async function activateTheme(
+	this: RequestUtils,
+	themeSlug: string
+): Promise< void > {
+	let response = await this.request.get( THEMES_URL );
+	const html = await response.text();
+	const optionalFolder = '([a-z0-9-]+%2F)?';
+
+	// The `optionalFolder` regex part matches paths with a folder,
+	// so it will return the first match, which might contain a folder.
+	// First try to honor the included theme slug, that is, without a folder.
+	let matchGroup = html.match(
+		`action=activate&amp;stylesheet=${ encodeURIComponent(
+			themeSlug
+		) }&amp;_wpnonce=[a-z0-9]+`
+	);
+
+	// If the theme is not found, try to match the theme slug with a folder.
+	if ( ! matchGroup ) {
+		matchGroup = html.match(
+			`action=activate&amp;stylesheet=${ optionalFolder }${ encodeURIComponent(
+				themeSlug
+			) }&amp;_wpnonce=[a-z0-9]+`
+		);
+	}
+
+	if ( ! matchGroup ) {
+		if ( html.includes( `data-slug="${ themeSlug }"` ) ) {
+			// The theme is already activated.
+			return;
+		}
+
+		throw new Error( `The theme "${ themeSlug }" is not installed` );
+	}
+
+	const [ activateQuery ] = matchGroup;
+	const activateLink =
+		THEMES_URL + `?${ activateQuery }`.replace( /&amp;/g, '&' );
+
+	response = await this.request.get( activateLink );
+
+	await response.dispose();
+}
+
+// https://developer.wordpress.org/rest-api/reference/themes/#definition
+async function getCurrentThemeGlobalStylesPostId( this: RequestUtils ) {
+	type ThemeItem = {
+		stylesheet: string;
+		status: string;
+		_links: { 'wp:user-global-styles': { href: string }[] };
+	};
+	const themes = await this.rest< ThemeItem[] >( {
+		path: '/wp/v2/themes',
+	} );
+	let themeGlobalStylesId: string = '';
+	if ( themes && themes.length ) {
+		const currentTheme: ThemeItem | undefined = themes.find(
+			( { status } ) => status === 'active'
+		);
+
+		const globalStylesURL =
+			currentTheme?._links?.[ 'wp:user-global-styles' ]?.[ 0 ]?.href;
+		if ( globalStylesURL ) {
+			// Extract the ID from the URL. The URL format depends on
+			// the permalink structure:
+			// - Plain: ?rest_route=/wp/v2/global-styles/123
+			// - Pretty: /wp-json/wp/v2/global-styles/123
+			const idMatch = globalStylesURL.match(
+				/\/wp\/v2\/global-styles\/(\d+)/
+			);
+			if ( idMatch ) {
+				themeGlobalStylesId = idMatch[ 1 ];
+			}
+		}
+	}
+	return themeGlobalStylesId;
+}
+
+/**
+ * Deletes all post revisions using the REST API.
+ *
+ * @param {}              this     RequestUtils.
+ * @param {string|number} parentId Post attributes.
+ */
+async function getThemeGlobalStylesRevisions(
+	this: RequestUtils,
+	parentId: number | string
+) {
+	// Lists all global styles revisions.
+	return await this.rest< Record< string, Object >[] >( {
+		path: `/wp/v2/global-styles/${ parentId }/revisions`,
+		params: {
+			per_page: 100,
+		},
+	} );
+}
+
+export {
+	activateTheme,
+	getCurrentThemeGlobalStylesPostId,
+	getThemeGlobalStylesRevisions,
+};