https://github.com/polylang/e2e-test-utils

End-to-end test utilities for Polylang projects.
https://github.com/polylang/e2e-test-utils

Last synced: 5 months ago
JSON representation

End-to-end test utilities for Polylang projects.

• Host: GitHub
• URL: https://github.com/polylang/e2e-test-utils
• Owner: polylang
• Created: 2025-04-02T11:30:54.000Z (about 1 year ago)
• Default Branch: master
• Last Pushed: 2026-01-16T11:33:15.000Z (5 months ago)
• Last Synced: 2026-01-17T01:16:53.353Z (5 months ago)
• Language: JavaScript
• Size: 21.5 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# 🧪 Polylang E2E Test Utils

This package provides shared E2E testing utilities for Polylang projects.

## 📦 Installation

```bash

npm install --save-dev polylang/e2e-test-utils

```

## 🚀 Usage

### ⚙️ Playwright configuration

Create a `playwright.config.js` file in your project's root:

```javascript

import { getPlaywrightConfig } from '@wpsyntex/e2e-test-utils';

export default getPlaywrightConfig( {

  // Override any default configuration here

  use: {

    // Custom use options

    globalSetup: require.resolve( 'path-to-your/global.setup.js' ), // Falls back to the packaged one.

  },

  webServer: {

    // Custom webServer options

  }

} );

```

#### Configuration Options

The `getPlaywrightConfig` function accepts an options object that can override any of the default configuration:

- `use`: Override default Playwright use options

- `webServer`: Override default webServer configuration

- Any other Playwright configuration options

#### Default Configuration

The default configuration includes:

- Chrome browser setup

- HTML reporter

- CI-specific settings

- Default storage state path

- Local development server configuration

### 📚 API Documentation

#### 🌐 Language Management Functions

##### `getAllLanguages( requestUtils )`

Retrieves a list of all configured languages in Polylang.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

- **Returns:** Promise resolving to the list of languages

##### `getLanguage( requestUtils, slug )`

Retrieves a specific language by its slug.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `slug`: Language slug to retrieve

- **Returns:** Promise resolving to the language data

##### `createLanguage( requestUtils, locale )`

Creates a new language in Polylang.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `locale`: Language locale to create (e.g., 'fr_FR')

- **Returns:** Promise resolving to the created language

##### `deleteLanguage( requestUtils, slug )`

Deletes a specific language by its slug.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `slug`: Language slug to delete

- **Returns:** Promise resolving to the deletion result

##### `deleteAllLanguages( requestUtils )`

Deletes all configured languages except the default one.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

- **Returns:** Promise resolving to the deletion results

#### ⚙️ Settings Management Functions

##### `getSettings( requestUtils )`

Retrieves all Polylang plugin settings.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

- **Returns:** Promise resolving to the settings object

##### `setSetting( requestUtils, settingKey, settingValue )`

Updates a specific plugin setting.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `settingKey`: The key of the setting to update

  - `settingValue`: The new value for the setting

- **Returns:** Promise resolving to the updated setting

##### `resetAllSettings( requestUtils )`

Resets all plugin settings to their default values.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

- **Returns:** Promise resolving to the reset operation result

- **Note:** Preserves the default language setting

#### 🏷️ Taxonomy Management Functions

##### `getAllTerms( requestUtils, taxonomy )`

Retrieves all terms for a specific taxonomy.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `taxonomy`: Taxonomy slug

- **Returns:** Promise resolving to the list of terms

##### `getTermBySlug( requestUtils, taxonomy, slug )`

Retrieves a specific term by its slug within a taxonomy.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `taxonomy`: Taxonomy slug

  - `slug`: Term slug to retrieve

- **Returns:** Promise resolving to the term data

##### `deleteAllTerms( requestUtils, taxonomy )`

Deletes all terms within a specific taxonomy.

- **Parameters:**

  - `requestUtils`: Gutenberg request utils object

  - `taxonomy`: Taxonomy slug

- **Returns:** Promise resolving to the deletion results

#### 📄 XLIFF Export Functions

##### `fillInXliffExportForm( page, options )`

Fills in the XLIFF export form for bulk translation export.

- **Parameters:**

  - `page`: Playwright page object

  - `options`: Configuration object

    - `postId`: Post ID to export

    - `postTitle`: Post title to select

    - `languageName`: Target language name

- **Returns:** Promise that resolves when the export form is submitted

- **Note:** Page should be on the post list table

##### `getXliffRegex( sourceLocale, targetLocale )`

Returns a regex pattern to match XLIFF file names with the specified locales and timestamp.

- **Parameters:**

  - `sourceLocale`: Source language locale (e.g., 'en_US')

  - `targetLocale`: Target language locale (e.g., 'fr_FR')

- **Returns:** RegExp object to match XLIFF file names

- **Note:** Converts underscores to hyphens in locales and matches timestamp pattern

#### 📥 Download Utilities

##### `getDownload( page, submitButtonOptions )`

Returns a download promise by clicking a submit button and waiting for the download to start.

- **Parameters:**

  - `page`: Playwright page object

  - `submitButtonOptions`: Submit button options (default: `{ name: 'Submit' }`)

- **Returns:** Promise resolving to the download object

##### `getStringFromFile( filePath )`

Reads a file and returns its contents as a string.

- **Parameters:**

  - `filePath`: The file path to read

- **Returns:** String content of the file

#### 🔧 Additional Exports

##### `globalSetup`

Global setup function for Playwright tests. Ensures fixtures are deleted and global context is set up properly.

#### 💡 Usage Example

```javascript

import {

  createLanguage,

  setSetting,

  getAllTerms

} from '@wpsyntex/e2e-test-utils';

// Create a new language

await createLanguage( requestUtils, 'fr_FR' );

// Update a setting

await setSetting( requestUtils, 'hide_default', true );

// Get all terms from a taxonomy

const terms = await getAllTerms( requestUtils, 'category' );

```

All these functions are designed to work with the Gutenberg request utils object and follow REST API patterns for interacting with Polylang's functionality. They provide a comprehensive set of tools for managing languages, settings, and taxonomies in E2E tests.