feat: new section - end to end testing with Kinde #637
Conversation
WalkthroughSix new documentation guides added covering Kinde authentication testing: backend API testing with Jest and refresh tokens, test user and environment setup, authenticated feature testing with Playwright, authentication flow testing via browser automation, passwordless OTP testing, and a central testing index. Sidebar navigation updated to expose the new Testing section. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying kinde-docs-preview with
|
| Latest commit: |
7fa9ff2
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://bb36c98c.kinde-docs-preview.pages.dev |
| Branch Preview URL: | https://tamal-feat-end-to-end-testin.kinde-docs-preview.pages.dev |
tamalchowdhury
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Fix all issues with AI Agents 🤖
In @src/content/docs/developer-tools/testing/setup-test-user-environment.mdx:
- Line 93: Replace the incorrect verb form "setup" in the sentence "Verify the
email address and setup a strong password" with the two-word verb "set up" so
the line reads "Verify the email address and set up a strong password"; locate
this exact phrase in
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx (look
for the sentence beginning with "Verify the email address") and update it
accordingly.
- Around line 52-53: The sentence "Sign in to your Kinde dashboard, select
**Production** arrow, a pop-up appears - Select **All environments**" contains a
comma splice; rewrite it as two or more clear clauses—for example, "Sign in to
your Kinde dashboard and click the **Production** arrow. When the pop-up
appears, select **All environments**." Update the text in
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx to
replace the original line with a version that removes the comma splice and
improves flow.
- Around line 75-77: The ordered list in setup-test-user-environment.mdx has
duplicate "3." entries; update the second "3." (the line "Select **Save**") to
"4." and renumber all following steps incrementally so the sequence progresses
correctly (e.g., change the "4." that follows to "5.", etc.) to restore proper
step ordering.
In @src/content/docs/developer-tools/testing/testing-authentication-flows.mdx:
- Around line 426-537: The example uses Playwright's page.fill() which is
incompatible with AWS Synthetic Canaries' Puppeteer Page; update the handler's
flowStep usages to call Puppeteer's page.type() instead of page.fill() wherever
you populate inputs (e.g., the fields in exports.handler:
'input[name="p_first_name"]', 'input[name="p_last_name"]',
'input[name="p_email"]' in the sign-up flow, the commented OTP step
'input[name="p_confirmation_code"]', the password creation fields
'input[name="p_first_password"]' and 'input[name="p_second_password"]', and the
sign-in fields 'input[name="p_email"]' and 'input[name="p_password"]'). Ensure
all page.fill(...) calls in the handler are replaced with page.type(...) so the
script uses Puppeteer-compatible APIs.
🧹 Nitpick comments (2)
src/content/docs/developer-tools/testing/index.mdx (1)
54-54: Consider clarifying MFA testing capabilities.The statement "may require manual intervention" is somewhat vague. Consider specifying what MFA testing is possible (e.g., testing with backup codes, testing the MFA setup flow) versus what requires manual intervention (e.g., actual authenticator app interaction).
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx (1)
56-56: Provide example for both environment name and code.The instruction mentions entering both "environment name and code" but only provides an example for the name. Consider adding an example code value (e.g., "TEST" or "test") to help users understand the expected format for both fields.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
src/content/docs/developer-tools/testing/backend-api-testing.mdxsrc/content/docs/developer-tools/testing/index.mdxsrc/content/docs/developer-tools/testing/setup-test-user-environment.mdxsrc/content/docs/developer-tools/testing/testing-authenticated-features-playwright.mdxsrc/content/docs/developer-tools/testing/testing-authentication-flows.mdxsrc/content/docs/developer-tools/testing/testing-passwordless-flows.mdxsrc/data/sidebarData.ts
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-27T18:42:29.479Z
Learnt from: victoreronmosele
Repo: kinde-oss/documentation PR: 647
File: src/content/docs/developer-tools/sdks/native/ios-sdk.mdx:278-297
Timestamp: 2025-12-27T18:42:29.479Z
Learning: In MDX documentation files (e.g., any API reference docs), when documenting parameters (like loginHint, connectionId), prefer listing them in the API reference Arguments section and link to detailed documentation pages instead of duplicating descriptions, format specs, or validation rules inline. This follows the 'document once, reference anywhere' principle.
Applied to files:
src/content/docs/developer-tools/testing/backend-api-testing.mdxsrc/content/docs/developer-tools/testing/testing-passwordless-flows.mdxsrc/content/docs/developer-tools/testing/testing-authentication-flows.mdxsrc/content/docs/developer-tools/testing/index.mdxsrc/content/docs/developer-tools/testing/testing-authenticated-features-playwright.mdxsrc/content/docs/developer-tools/testing/setup-test-user-environment.mdx
🪛 LanguageTool
src/content/docs/developer-tools/testing/backend-api-testing.mdx
[grammar] ~88-~88: Ensure spelling is correct
Context: ...the placeholder values with your actual Kinde credentials from Step 1. <Aside ty...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/content/docs/developer-tools/testing/testing-passwordless-flows.mdx
[grammar] ~380-~380: Use a hyphen to join words.
Context: ...n-in flow To test the passwordless sign in flow: 1. Enable the Email + code...
(QB_NEW_EN_HYPHEN)
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx
[grammar] ~60-~60: Ensure spelling is correct
Context: ...management | ## Testing sign-up flows Kinde requires OTP email verification when si...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~66-~66: Use a hyphen to join words.
Context: ... email testing service to test user sign up 3. Verify redirect: Check that us...
(QB_NEW_EN_HYPHEN)
[grammar] ~228-~228: Use a hyphen to join words.
Context: ...-a8b7236e3300/public) ### Example: Sign up flow with Playwright Check out the f...
(QB_NEW_EN_HYPHEN)
[grammar] ~385-~385: Use a hyphen to join words.
Context: ...-16576792a600/public) ### Example: Sign up flow with Cypress ```ts // spec.cy.t...
(QB_NEW_EN_HYPHEN)
src/content/docs/developer-tools/testing/testing-authenticated-features-playwright.mdx
[style] ~37-~37: Try moving the adverb to make the sentence clearer.
Context: ...ling passwordless flows. --- Learn how to efficiently test authenticated features in applications using Kinde authenticat...
(SPLIT_INFINITIVE)
[grammar] ~438-~438: Ensure spelling is correct
Context: ...ecrets with the new refresh token. ### Kinde form selectors changed Kinde may updat...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (13)
src/content/docs/developer-tools/testing/backend-api-testing.mdx (2)
104-142: LGTM! Token refresh implementation is well-structured.The token refresh logic properly handles errors and falls back to existing tokens if refresh fails, which ensures tests can still run with cached credentials. Good use of environment variables and clear error messages.
223-249: LGTM! Excellent security guidance and limitations.The documentation properly covers token rotation behavior, secure storage requirements, and testing limitations. The best practices section provides actionable security recommendations.
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx (3)
48-58: LGTM! Helpful tool comparison.The comparison table provides clear pros/cons for different browser automation tools, helping developers choose the right approach for their needs.
174-218: LGTM! Playwright test examples are correct.The test examples properly use Playwright's API, handle redirects with URL expectations, and verify authentication state. Good use of test-id attributes for reliable selectors.
330-375: LGTM! Cypress examples properly handle cross-origin flows.The test examples correctly use
cy.origin()to handle Kinde's authentication on a different domain, which is essential for Cypress testing. Good use of environment variables for configuration.src/content/docs/developer-tools/testing/testing-passwordless-flows.mdx (2)
49-263: LGTM! Comprehensive OTP testing approaches.The documentation covers multiple practical approaches for capturing OTP codes (Mailosaur, Mailtrap, AWS S3, database, IMAP), with correct API usage and proper error handling. The regex pattern for extracting 6-digit codes is reliable.
317-519: LGTM! Well-structured Playwright + Mailosaur integration.The test examples demonstrate proper integration between Playwright and Mailosaur for OTP extraction. Good practices include unique email generation, cleanup steps, and storage state persistence.
src/data/sidebarData.ts (1)
70-74: LGTM! Sidebar entry correctly configured.The new Testing section is properly added under "SDKs and APIs" with the correct directory path and sensible defaults. The
collapsed: falsesetting ensures the new documentation is immediately visible to users.src/content/docs/developer-tools/testing/testing-authenticated-features-playwright.mdx (4)
83-180: LGTM! Excellent authentication state reuse pattern.The implementation correctly uses Playwright's storage state feature to authenticate once and reuse across tests. The setup/dependency pattern is properly configured, and the auth verification step ensures state is saved only after successful login.
206-298: LGTM! Solid API testing implementation with token refresh.The token refresh setup properly persists tokens to a file and the API tests correctly read and use them. Good use of Playwright's request fixture for API testing, and the console log reminder about updating the refresh token is helpful.
365-408: LGTM! Well-structured CI/CD integration.The GitHub Actions workflow properly installs dependencies, Playwright browsers, and runs tests with secrets injected from repository settings. Good inclusion of artifact upload for test reports.
410-454: LGTM! Comprehensive troubleshooting guidance.The troubleshooting section addresses common issues (navigation timeouts, auth state persistence, token expiry, form selector changes) with practical solutions. Best practices emphasize security and reliability.
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx (1)
85-87: Consider moving the example repository to the official Kinde organization for consistency.The Kinde Next.js test application is currently hosted under a personal account rather than the
kinde-ossorganization. While the repository is accessible and functional, consolidating examples under the official organization would improve discoverability and clarify official support status. For reference, most other examples and starter kits in this documentation are hosted underkinde-ossorkinde-starter-kits.⛔ Skipped due to learnings
Learnt from: clairekinde11 Repo: kinde-oss/documentation PR: 545 File: src/content/docs/design/customize-with-code/custom-styling-per-application.mdx:59-70 Timestamp: 2025-09-04T02:15:38.458Z Learning: In Kinde custom pages repository structure, layout.tsx should be placed as a sibling to the (kinde) directory at pages/layout.tsx level, not inside the (kinde) directory. The import path "../../layout" from pages/(kinde)/(default)/page.tsx works correctly with this structure in Kinde's system.Learnt from: DaveOrDead Repo: kinde-oss/documentation PR: 402 File: src/content/docs/workflows/bindings/fetch-binding.mdx:42-47 Timestamp: 2025-04-24T03:46:44.953Z Learning: The correct import path for the Kinde infrastructure library is `kinde/infrastructure`, not `kinde-oss/infrastructure`, despite the GitHub repository being at kinde-oss/infrastructure.Learnt from: marcosmartini Repo: kinde-oss/documentation PR: 226 File: src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx:0-0 Timestamp: 2024-10-22T06:12:51.559Z Learning: The Kinde documentation's base URL is not `kinde.com`, so links to the documentation should use the correct base URL.
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/developer-tools/testing/setup-test-user-environment.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 2
Fix all issues with AI Agents 🤖
In @src/content/docs/developer-tools/testing/testing-authentication-flows.mdx:
- Line 364: The click call using cy.get('button[type="submit"]').click({
multiple: true }) will click all matching submit buttons; remove the unnecessary
{ multiple: true } option and use cy.get('button[type="submit"]').click() (or
explicitly target a single element with .first()/.eq(n) before .click() if a
specific button is intended) to ensure only one submit button is clicked.
- Line 347: The Cypress click call is using an unnecessary { multiple: true }
option which will click all matched submit buttons; update the
cy.get('button[type="submit"]').click call in the testing-authentication-flows
content to remove the multiple option so it clicks a single submit button (i.e.,
change the click invocation on the selector cy.get('button[type="submit"]') to
call .click() with no options).
🧹 Nitpick comments (1)
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx (1)
550-550: Consider adding explicit setup guidance for test IDs.The examples throughout this guide rely on data-testid attributes (e.g.,
[data-testid="sign-in-button"]), but there's no explicit mention that users need to add these attributes to their application code before running the tests. Consider adding a brief setup note in the prerequisites section or early in the guide.Example addition for the "What you need" section:
- Test IDs added to your application's UI elements: - `[data-testid="sign-in-button"]` on your sign-in button - `[data-testid="sign-up-button"]` on your sign-up button - `[data-testid="sign-out-button"]` on your sign-out button - `[data-testid="user-profile"]` on an element visible when authenticated
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/content/docs/developer-tools/testing/setup-test-user-environment.mdxsrc/content/docs/developer-tools/testing/testing-authentication-flows.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- src/content/docs/developer-tools/testing/setup-test-user-environment.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-27T18:42:29.479Z
Learnt from: victoreronmosele
Repo: kinde-oss/documentation PR: 647
File: src/content/docs/developer-tools/sdks/native/ios-sdk.mdx:278-297
Timestamp: 2025-12-27T18:42:29.479Z
Learning: In MDX documentation files (e.g., any API reference docs), when documenting parameters (like loginHint, connectionId), prefer listing them in the API reference Arguments section and link to detailed documentation pages instead of duplicating descriptions, format specs, or validation rules inline. This follows the 'document once, reference anywhere' principle.
Applied to files:
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx
🪛 LanguageTool
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx
[grammar] ~60-~60: Ensure spelling is correct
Context: ...management | ## Testing sign-up flows Kinde requires OTP email verification when si...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~66-~66: Use a hyphen to join words.
Context: ... email testing service to test user sign up 3. Verify redirect: Check that us...
(QB_NEW_EN_HYPHEN)
[grammar] ~228-~228: Use a hyphen to join words.
Context: ...-a8b7236e3300/public) ### Example: Sign up flow with Playwright Check out the f...
(QB_NEW_EN_HYPHEN)
[grammar] ~385-~385: Use a hyphen to join words.
Context: ...-16576792a600/public) ### Example: Sign up flow with Cypress ```ts // spec.cy.t...
(QB_NEW_EN_HYPHEN)
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx
Show resolved
Hide resolved
src/content/docs/developer-tools/testing/testing-authentication-flows.mdx
Show resolved
Hide resolved
|
Hi @tamalchowdhury , I was reviewing the "Backend API testing with Jest" guide. From the example, it appears that the guide is currently demonstrating how to call Kinde Account APIs (for example, /oauth2/v2/user_profile) using a refreshed access token. This is useful for validating authentication and token rotation. If this was the intended goal of the guide, then the current approach makes sense. However, if the intent was to demonstrate how customers can test their own backend APIs protected by Kinde, then the example may need to be adjusted, as it does not currently show calling or validating a customer-managed backend API. If the goal is to test client-managed backend APIs secured by Kinde, I think we need to adjust the guide and add a few missing pieces: 1. Prerequisite: Register the backend API in Kinde The backend API must first be registered and managed in Kinde. 2. Audience must be included when issuing tokens When obtaining access and refresh tokens, the audience parameter should be included:
This ensures the access token is scoped for the customer’s backend API, not just Kinde’s Account APIs. 3. Calling the customer’s backend API (not Kinde’s) The refreshed access token should then be used to call a protected customer API endpoint, rather than a Kinde endpoint like 4. Backend token validation using a Kinde SDK If the API is protected, the backend should validate the token using the appropriate SDK, for example:
The guide should show how the backend validates the token and enforces scopes or permissions. 5. End-to-end test example A complete example test would ideally show:
Another small improvement suggestion: could you hide your name in the demo screenshot? Adding a simple white box over it would be enough, mainly to protect your own identity. Relevant references Custom API scopes Register and manage APIs Backend SDKs (Node / Express / GraphQL) If you decide to implement this yourself, the steps should be fairly clear. This guide is intended as a high-level outline, and more detailed implementation guidance can be found in the Kinde documentation or by using Kinde AI. Please let me know if anything is unclear or if there’s any area where I can help further. I’m also reviewing other guides and will share feedback as I come across additional opportunities for improvement. |
|
|
||
| // Important: Update your secrets manager with the new refresh token | ||
| // for subsequent test runs | ||
| console.log('New refresh token (update in secrets):', tokens.refresh_token) |
There was a problem hiding this comment.
This console.log prints a fresh refresh_token into CI logs, which is effectively a credential leak (and often ends up in build logs/artifacts). Can we change this guidance to not output the token, and instead say something like “persist the new refresh token to your secret store out-of-band” (or recommend using a refresh token that does not rotate / a different approach), without ever logging it?
| test('should get user profile', async () => { | ||
| const response = await fetch( | ||
| `${KINDE_ISSUER_URL}/oauth2/v2/user_profile`, | ||
| { |
There was a problem hiding this comment.
This example is calling Kinde’s Account API (/oauth2/v2/user_profile) rather than demonstrating “test your backend API with Jest” (matches @Arobce’s concern). I suggest either (a) reframe this page explicitly as “Testing Kinde Account APIs + token rotation”, or (b) update the example to call a customer backend endpoint (e.g. https://api.yourapp.com/...) and include the missing pieces: audience/resource API, and guidance that the backend must validate the JWT (iss/aud/exp + signature) before trusting it.
| 4. Navigate to the **Application** tab and select **Cookies** > `http://localhost:3000` | ||
| 5. Select the `refresh_token` and `access_token` cookies and copy their values, you will need these in the next step | ||
|
|
||
|  |
There was a problem hiding this comment.
Screenshot hygiene: this is externally hosted and may contain PII/org identifiers (and could change/expire). Recommend redacting any identifying info and hosting the image in-repo under src/assets/images (or another stable docs asset path) so we control permanence and future diffs.
|
|
||
| 1. Sign in to your Kinde dashboard and select the **Production** arrow. A pop-up appears. | ||
| - Select **All environments** | ||
|  |
There was a problem hiding this comment.
Same screenshot concern here: please ensure screenshots are redacted (no real emails/org names) and consider moving from external image hosting to repo-managed assets for long-term stability.
|
|
||
| Optional: Go to **Tokens** where you can configure a custom token expiration time. | ||
|
|
||
| You can use the [Kinde Next.js test application](https://github.com/tamalchowdhury/kinde-test-application) to run your tests locally. |
There was a problem hiding this comment.
Governance/support clarity: this links to an example repo under a personal account. Can we pick an example repo under kinde-oss/kinde-starter-kits?
Description (required)
This PR creates a new e2e testing section with Kinde
A total of 6 docs make up this new section with option to expand based on testing tools (Cypress, Playwright)
Sits under SDK and APIs
Related issues & labels (optional)
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.