@lifterlms/llms-e2e-test-utils

LifterLMS E2E Test Utilities

End-To-End (E2E) test utilities for LifterLMS (and WordPress). This package extends functionality provided by @wordpress/e2e-test-utils, adding functionality specifically for testing LifterLMS projects and add-ons.

Installation

Install the module

npm install --save-dev @lifterlms/llms-e2e-test-utils`

Changelog

View the Changelog

API Docs

activateTheme

Activates a theme.

Parameters

• theme ?string: Accepts a theme slug. If not supplied, loads the default theme for the tested WP version.

Returns

• Promise: Promise that resolves when the theme is activated.

clearBlocks

Deletes all blocks in the editor.

Returns

• Promise: Promise from page.evaluate().

click

Click an elements by selector

Parameters

• selector string: Element selector string.

Returns

• void:

clickAndWait

Click an element and wait for navigation.

Parameters

• selector string: Query selector for the DOM element to click.
• waitUntil string: Network connection to wait for, defaults to 'networkidle2'.

Returns

• void:

clickElementByText

Click an element by Text

Parameters

• string string: Case-insensitive string to search.
• selector string: Selector to search. Default "*".

Returns

• void:

createAccessPlan

Create and publish a new course

Parameters

• args Object: Creation arguments.
• args.postId number: Post ID of the plan's course or membership.
• args.price number: Plan price.
• args.title string: Plan title.

Returns

• string: The created plan's purchase link URL.

createCertificate

Create and publish a new certificate

Type

• numbercertificateId WP Post ID of the created certificate post.
• numberengagementId WP Post ID of the created engagement post. }

Parameters

• args Object: Optional creation arguments.
• args.title string: Certificate title.
• args.content string: HTML content of the certificate.
• args.adminTitle string: Admin title.
• args.engagement string: If supplied, also creates an engagement trigger. This should be the ID of a trigger

Returns

• Object: { Object containing information about the created post(s).

createCoupon

Create and publish a new course

Parameters

• args Object: Creation arguments.
• args.code string: Coupon code (post title).
• args.discount string: The discount amount with either a leading $ to specify dollar amount discounts or a trailing % for percentage discounts.

Returns

• string: The coupon code.

createCourse

Create and publish a new course

Parameters

• title string: Course title.

Returns

• number: The created course's WP_Post ID.

createEngagement

Create and publish a new certificate

Parameters

• engagementId number: WP_Post ID of the a certificate, email, or achievement post.
• args Object: Optional creation arguments.
• args.title string: Engagement title.
• args.trigger string: ID of the engagement trigger event.
• args.type string: Engagement type: certificate, email, or achievement.
• args.delay number: Engagement delay, in days.

Returns

• number: WP Post ID of the created certificate post.

createMembership

Create and publish a new membership

Parameters

• title string: Membership title.

Returns

• number: The created membership's WP_Post ID.

createPost

Create and publish a new post

Parameters

• postType string: WP_Post type.
• title string: Post title.
• content ?string: Post content.

Returns

• number: The created post's WP_Post ID.

createUser

Create a new user.

Parameters

• opts Object: Hash of user information used to create the new user.

Returns

• Object: Object of created user data.

createVoucher

Create and publish a new course

Parameters

• args Object: Creation arguments.
• args.name string: Voucher (post) title.
• args.course string: Name of a course to add to the voucher.
• args.membership string: Name of a membership to add to the voucher.
• args.codes number: Number of codes to generate.
• args.uses number: Number of uses per code.

Returns

• string[]: Array of the generated voucher codes.

dismissEditorWelcomeGuide

Dismiss the "Welcome Guide" in the block editor (if it's active)

Returns

• void:

enrollStudent

Enroll a student into a course

This performs as "manual" enrollment using the enrollment area on the course or membership.

Parameters

• postId number: WP_Post ID.
• studentId number: WP_User ID.

Returns

• void:

fillField

Type text into a field identified by a selector.

Parameters

• selector string: Query selector to identify the field element.
• text string: Text to type into the field.

Returns

• void:

findElementByText

Find an element by Text

Related

Parameters

• string string: Case-insensitive string to search.
• selector string: Selector to search. Default "*".

Returns

• Array: Element.

getAllBlocks

Retrieves a list of blocks in the editor, with or without client IDs.

Specifying withClientIds=false allows using the resulting array of block objects in snapshots without having to specify a snapshot matcher that excludes (possibly nested) blocks with clientIds that will not match future test runs.

Parameters

• withClientIds boolean: Whether or not to exclude clientIds.

Returns

• Object[]: Array of block objects.

getPostTitleSelector

Retrieves the CSS selector for the post's title element.

On 5.9+ we're testing against the 2022 theme, on 5.8 & earlier we're using 2021.

Returns

• Promise: A promise that resolves to return the element's text content.

getPostTitleTextContent

Retrieves the textContent of the lesson post's title element.

This function uses a dynamically-determined selector based on the current WP version (and assumed theme) run by default with that version.

Returns

• Promise: A promise that resolves to return the element's text content.

getWPVersion

Retrieve the WP_VERSION environment variable

When running tests locally this will likely be undefined unless running tests with WP_VERSION=5.7.2 npm run test.

The WP_VERSION env var is defined during CI tests automatically and this function is generally used to determine conditionals based on the WP Core version.

For example: block editor selectors change between WP core version, some features aren't available on older versions, etc...

Returns

• ?string: WordPress version or null if not set.

highlightNode

Highlight (selects) the contents of a node.

Parameters

• selector string: Query selector.
• copySelection boolean: If true, copies the selected text and returns it. The browser clipboard-read permission must be granted in order to read from the clipboard.

Returns

• boolean|string: Returns the copied text or true if copySelection is false.

importCourse

Import a course JSON file

Parameters

• importFile string: Filename of the import.
• importPath string: Local path where the file is located. By default uses tests/assets/.
• navigate boolean: Whether or not to automatically navigate to the imported course when done.

Returns

• void:

loginStudent

Login a user via the LifterLMS student dashboard.

Parameters

• login string: User login or email address.
• pass string: User password.

Returns

• void:

logoutUser

Logout the current user.

Returns

• Promise: Promise which resolves after the user is logged out and the page reloaded.

openSidebarPanelTab

Opens a sidebar panel tab if it's not already open.

Parameters

• tab string: Tab to select, accepts "primary" to select the main document settings tab or "block" to select the block tab.

Returns

• Promise: A promise that resolves when the desired panel becomes active.

publishPost

Disables prepublish checks and clicks the post publish button.

Returns

• Promise: Promise which resolves when the close button element is successfully clicked.

registerStudent

Register a new student via the LifterLMS Open Registration Page

Type

• stringemail User's email address.
• stringpass User's password. }

Parameters

• args Object: Function arguments object.
• args.email string: Email address. If not supplied one will be created from the first name and last name.
• args.pass string: User password. If not supplied one will be automatically generated.
• args.first string: User's first name.
• args.last string: User's last name.
• args.voucher string: Voucher code to use during registration.
• args.address1 string: User's address line 1.
• args.address2 string: User's address line 2.
• args.city string: User's city.
• args.country string: User's country.
• args.state string: User's state.
• args.postcode string: User's postcode.
• args.phone string: User's phone.

Returns

• Object: { Object containing information about the newly created user.

runSetupWizard

Run (and test) the LifterLMS Setup Wizard

Parameters

• options Object: Options object.
• options.coursesToImport string[]: Titles of the course(s) to import through the setup wizard. Pass a falsy to skip import and "Start from Scratch".
• options.exit boolean: Whether or not to exit the setup wizard at the conclusion of setup. If true, uses the "Exit" link to leave setup.`

Returns

• void:

select2Select

Select a value from a select2 dropdown field

Parameters

• selector string: Query selector for the select element.
• value string: Option value to select.

Returns

• void:

setCheckboxSetting

Toggles a LifterLMS checkbox setting.

Parameters

• selector string: Selector for the setting checkbox.
• status boolean: Requested setting status. Use true for checked and false for unchecked.
• save boolean: Whether or not to perform a save after updating the setting.

Returns

• void:

setSelect2Option

Set the value of a select2 dropdown field

This does not actually test whether or not select2 is working, instead it selects the value on the select element and artificially triggers a change event.

Parameters

• selector string: Query selector for the select element.
• value string: Option value to select.
• create boolean: If true, the value will be added to the select element before being selected. This is a useful option for AJAX powered select2 elements that will be empty until interacted with.

Returns

• void:

toggleOpenRegistration

Toggles the open registration setting on or off

Parameters

• status boolean: Whether to toggle on (true) or off (false).

Returns

• void:

toggleSidebarPanel

Opens or closes an editor sidebar panel based on the panel's title.

Parameters

• title string: The panel title to open or close.
• shouldBeOpen boolean: Whether or not the panel should be open.

Returns

• Object|undefined: A puppeteer ElementHandle object if found.

updatePost

Clicks the button to save / update a post in the block editor.

Returns

• Promise: A promise that resolves when the button is successfully pressed.

visitPage

Visits a page on the WordPress site.

Parameters

• path string: URL path. Eg: "dashboard" to visit mysite.com/dashboard.
• query string: Query string to be added to the url. Eg: "myvar=1&anothervar=2".

Returns

• void:

visitPostPermalink

Visits a post on the frontend by from within the block editor.

Returns

• Promise: A promise representing the link click.

visitSettingsPage

Visit a LifterLMS Settings Page on the admin panel

Parameters

• args Object: Arguments object.
• args.tab string: Settings page tab ID.
• args.section string: Settings page section ID.

Returns

• void:

wpVersionCompare

Run a version compare against the currently tested version of WordPress.

Parameters

• version string: A version string.
• comparator string: A comparison string, eg ">=" or "<", etc...
• majorMinorOnly boolean: If true, only uses the major and minor versions of the current WP version. For example, version 5.9.1 will be shortened to 5.9 for comparison purposes.

Returns

• boolean: Comparison result.