@lifterlms/llms-e2e-test-utils
v4.0.1
Published
E2E testing utilities for LifterLMS projects.
Downloads
417
Readme
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
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
number
certificateId WP Post ID of the created certificate post.number
engagementId 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
: Iftrue
, 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 ortrue
ifcopySelection
isfalse
.
importCourse
Import a course JSON file
Parameters
- importFile
string
: Filename of the import. - importPath
string
: Local path where the file is located. By default usestests/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
string
email User's email address.string
pass 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. Iftrue
, 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. Usetrue
for checked andfalse
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
: Iftrue
, 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
: Iftrue
, 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.