Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for Playwright helpers #1529

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

anagstef
Copy link
Member

@anagstef anagstef commented Sep 12, 2024

⚠️ We first need to release this: clerk/javascript#4006

This PR:

  • Adds documentation for helper functions in the Playwright integration of the @clerk/testing package.

@anagstef anagstef self-assigned this Sep 12, 2024
Copy link

Hey, here’s your docs preview: https://clerk.com/docs/pr/1529

## Test Helpers

The `@clerk/testing` package also provides some helper functions to sign in/sign out with Clerk in your Playwright tests without having to interact with the UI.
To use these commands, you just have to import the `clerk` object from the `@clerk/testing/playwright` package.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing "just do X" to not make feel people who struggle with the instructions after it

Suggested change
To use these commands, you just have to import the `clerk` object from the `@clerk/testing/playwright` package.
To use these commands, import the `clerk` object from the `@clerk/testing/playwright` package.


### `clerk.signIn`

The `clerk.signIn` function is used to sign in a user using Clerk. This helper supports only the following first factor strategies:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `clerk.signIn` function is used to sign in a user using Clerk. This helper supports only the following first factor strategies:
The `clerk.signIn()` function is used to sign in a user using Clerk. This helper supports only the following first factor strategies:

Multi-factor authentication is not supported.

> [!NOTE]
> This helper function internally uses the `setupClerkTestingToken()` helper, so you don't need to call it separately.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> This helper function internally uses the `setupClerkTestingToken()` helper, so you don't need to call it separately.
> `clerk.signIn()` internally uses the `setupClerkTestingToken()` helper, so you don't need to call it separately.

To not repeat "helper"

Comment on lines +99 to +100
- Before calling this function, you must call `page.goto`.
- Before using this function, navigate to a non-protected page that loads Clerk.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Before calling this function, you must call `page.goto`.
- Before using this function, navigate to a non-protected page that loads Clerk.
- Navigate to a non-protected page that loads Clerk via `page.goto()`, for example the index page


#### Parameters

`clerk.signIn` accepts an object with the following properties:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`clerk.signIn` accepts an object with the following properties:
`clerk.signIn()` accepts an object with the following properties:


#### Example

The following example demonstrates how to use the `clerk.signOut` helper in a test to sign a user out.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following example demonstrates how to use the `clerk.signOut` helper in a test to sign a user out.
The following example demonstrates how to use `clerk.signOut()` in a test to sign out a user.


### `clerk.loaded`

The `clerk.loaded` function asserts that Clerk has been loaded.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `clerk.loaded` function asserts that Clerk has been loaded.
`clerk.loaded()` asserts that Clerk has been loaded.

Comment on lines +222 to +223
- Before calling this command, you must call `page.goto`.
- Before using this command, navigate to a page that loads Clerk.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Before calling this command, you must call `page.goto`.
- Before using this command, navigate to a page that loads Clerk.
- Navigate to a non-protected page that loads Clerk via `page.goto()`, for example the index page


#### Parameters

`clerk.loaded` accepts an object with the following properties:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`clerk.loaded` accepts an object with the following properties:
`clerk.loaded()` accepts an object with the following properties:


#### Example

The following example demonstrates how to use the `clerk.loaded` helper in a test to assert that Clerk has been loaded.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following example demonstrates how to use the `clerk.loaded` helper in a test to assert that Clerk has been loaded.
The following example demonstrates how to use `clerk.loaded()` in a test to assert that Clerk has been loaded.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants