fix: add more documentation and Playwright guidance [🤖 automated] (#89)

> [!NOTE]
> 🤖 This PR was generated by HeiBot from the following prompt:
> > Proceed with improvements to the documentation. While you're at it,
a recent upgrade caused the docs to no longer show the root README.md in
the docusaurus pages as the default home page. Let's restore that
functionality and ensure the embedded image is also shown/published.
> > make sure to run prettier formatter afterwards so files use valid
formatting.

---

## Summary
- replace the custom Docusaurus landing page with a generated homepage
synced from the repository root `README.md`
- copy README media assets into the docs static output and wire homepage
sync into the docs `start`, `build`, and `deploy` scripts
- add a dedicated Playwright guide for installing Laika interceptors
before initial requests fire, and link it from the README and existing
docs pages
- fix the stale API-reference link used from the README/homepage flow

## Testing
- `yarn rrun prettier --check README.md docs/README.md docs/package.json
docs/sidebars.js docs/scripts/sync-homepage-from-readme.mjs
docs/src/pages/index.mdx docs/docs/how-to-install.md
docs/docs/resetting-between-tests.md docs/docs/usage-in-playwright.md`
- `cd docs && yarn build`

## Notes
- removed the old custom React landing page and its unused CSS module in
favor of the generated README-backed MDX page
- verified the built homepage now emits `/laika/media/...` asset URLs so
the embedded README images publish correctly under the site base path

---

> [!TIP]
> **💬 To make additional changes**, continue the conversation in the
original Slack thread, or trigger a new workflow dispatch with
`restore-session-from-run-id: 23865408578`.
<!-- HEIBOT_RUN_ID:24852762143 -->

---------

Co-authored-by: HeiBot Agent <183646609+zendesk-heibot[bot]@users.noreply.github.com>
Co-authored-by: Bazyli Brzóska <bbrzoska@zendesk.com>
Co-authored-by: Codex <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

Author: 3 people

README.md

@@ -10,7 +10,7 @@ Read the Medium article about Laika: [Mock GraphQL Subscriptions with Laika —
 
 ## Features
 
-- **mock** responses in either unit tests or browser tests (think Puppeteer or Cypress)
+- **mock** responses in either unit tests or browser tests (think Playwright, Puppeteer or Cypress)
   - simulate error state
   - simulate loading state
   - simulate subscriptions (pushing data to the client at any given point)
@@ -25,11 +25,16 @@ Read the Medium article about Laika: [Mock GraphQL Subscriptions with Laika —
 
 - Peer support: `@apollo/client` `>=3.2.5 <5`, `graphql` `^15 || ^16`, and `rxjs` `^7.3.0` for Apollo Client 4.x projects
 - [How to install](https://zendesk.github.io/laika/docs/how-to-install)
+- [Conditionally loading Laika](https://zendesk.github.io/laika/docs/loading-laika-conditionally)
+- [Testing approach](https://zendesk.github.io/laika/docs/testing-approach)
+- [Usage in Playwright](https://zendesk.github.io/laika/docs/usage-in-playwright)
+- [Usage in Jest / Vitest](https://zendesk.github.io/laika/docs/usage-in-jest-vitest)
 - [Usage in Cypress](https://zendesk.github.io/laika/docs/usage-in-cypress)
+- [Advanced usage](https://zendesk.github.io/laika/docs/advanced-usage)
 - [Resetting Between Tests](https://zendesk.github.io/laika/docs/resetting-between-tests)
 - [Logging and recording](https://zendesk.github.io/laika/docs/logging-and-recording)
 - [Pitfalls](https://zendesk.github.io/laika/docs/pitfalls)
-- [API reference](https://zendesk.github.io/laika/docs/api/interfaces/Laika)
+- [API reference](https://zendesk.github.io/laika/docs/api)
 
 ## Alternatives
 

docs/.gitignore

@@ -8,6 +8,7 @@
 .docusaurus
 .cache-loader
 /docs/api
+/static/readme-media
 /typedoc-sidebar.js
 
 # Misc

docs/README.md

@@ -1,20 +1,27 @@
 # Website
 
-This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ## Installation
 
 ```console
-yarn install
+cd ..
+yarn install --immutable
+
+cd docs
+yarn install --immutable
 ```
 
+The docs site generates API reference pages from the package source, so the root workspace dependencies and generated `tsconfig.json` need to exist. The docs scripts will bootstrap those root dependencies automatically if they are missing, but installing both workspaces upfront is faster and keeps the setup explicit.
+
 ## Local Development
 
 ```console
 yarn start
 ```
 
-This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
+This command starts a local development server and opens a browser window. Most changes are reflected live without having to restart the server.
+The docs home at `/docs/` is generated from the repository root `README.md` before the site starts or builds. The generated README page, copied README media, and generated API reference docs all stay gitignored.
 
 ## Build
 

docs/docs/.gitignore

@@ -1 +1,2 @@
 api
+readme.mdx

docs/docs/advanced-usage.md

@@ -0,0 +1,148 @@
+---
+id: 'advanced-usage'
+title: 'Advanced Usage'
+sidebar_label: 'Advanced Usage'
+custom_edit_url: null
+hide_title: true
+---
+
+# Advanced Usage
+
+Laika exposes a few capabilities that are easy to miss if you only start from the basic `intercept(...).mockResult(...)` flow.
+
+## Match more precisely
+
+Interceptors can match on:
+
+- `operationName`
+- `operation`
+- `variables`
+- `clientName`
+- `feature`
+- a custom matcher function
+
+```ts
+const interceptor = laika.intercept({
+  clientName: 'support-web',
+  feature: 'ticket-sidebar',
+  operationName: 'GetTicket',
+  variables: { id: '123' },
+})
+```
+
+If another link tags the operation context with `feature`, you can use that to scope logging and mocking more narrowly.
+
+Every interceptor also records its matched variables in `interceptor.calls`, similar to `jest.fn().mock.calls`.
+
+## Queue responses and choose how long they live
+
+Use `mockResultOnce()` when a response should be consumed a limited number of times:
+
+```ts
+const interceptor = laika.intercept({ operationName: 'GetUsers' })
+
+interceptor
+  .mockResultOnce({ result: { data: { users: [{ id: '1' }] } } })
+  .mockResultOnce({ result: { data: { users: [{ id: '2' }] } } })
+  .mockResult({ result: { data: { users: [] } } })
+```
+
+Use:
+
+- `mockReset()` to clear the current mock configuration but keep the interceptor registered
+- `mockRestore()` to remove just that interceptor
+- `mockRestoreAll()` to remove every interceptor created by the `Laika` instance
+
+## Wait for subscriptions and mount events
+
+You can wait for the next matching operation:
+
+```ts
+const interceptor = laika.intercept({ operationName: 'GetUsers' })
+
+await interceptor.waitForNextSubscription()
+```
+
+Or attach a lifecycle callback:
+
+```ts
+const interceptor = laika.intercept({ operationName: 'GetUsers' })
+
+interceptor.onSubscribe(({ operation, observer }) => {
+  if (operation.variables.preview) {
+    observer.next?.({
+      data: {
+        users: [],
+      },
+    })
+    observer.complete?.()
+  }
+})
+```
+
+Return a cleanup function from `onSubscribe()` if the interceptor needs to dispose any test-local state when the observer disconnects.
+
+## Turn off network fallback
+
+By default, unmatched queries and mutations can still fall through to the next Apollo link. If you want a request to stay in a loading state until your test explicitly responds, disable that fallback:
+
+```ts
+const interceptor = laika.intercept({ operationName: 'GetUsers' })
+
+interceptor.disableNetworkFallback()
+
+interceptor.onSubscribe(({ observer }) => {
+  observer.next?.({
+    data: {
+      users: [{ id: '1', name: 'Mouse' }],
+    },
+  })
+  observer.complete?.()
+})
+```
+
+Use `allowNetworkFallback()` to restore the default passthrough behavior.
+
+## Modify real backend responses without fully mocking them
+
+`modifyRemote()` is the higher-level API for the "let the request go through, then adjust the result" pattern:
+
+```ts
+laika.modifyRemote({ operationName: 'GetTicket' }, (result) => ({
+  ...result,
+  data: {
+    ...result.data,
+    injectedByLaika: true,
+  },
+}))
+```
+
+This is useful for fuzzing edge cases while still exercising the real backend response shape.
+
+## Customize the global singleton
+
+`createGlobalLaikaLink()` and `createLazyLoadableLaikaLink()` support a few options that are easy to overlook:
+
+```ts
+createLazyLoadableLaikaLink({
+  clientName: 'support-web',
+  globalPropertyName: 'supportLaika',
+  startLoggingImmediately: true,
+  onLaikaReady: (laika) => {
+    laika.log.startRecording('opening a ticket')
+  },
+})
+```
+
+This changes the singleton name from `window.laika` to `window.supportLaika`.
+
+Browser tests can hook into the same lifecycle with:
+
+```ts
+window.supportLaikaReadyCallbacks = window.supportLaikaReadyCallbacks ?? []
+window.supportLaikaReadyCallbacks.push((laika) => {
+  laika.intercept({ operationName: 'GetTicket' })
+})
+```
+
+See [Usage in Playwright](pathname:///docs/usage-in-playwright) and [Usage in Cypress](pathname:///docs/usage-in-cypress) for the browser-runner patterns built on top of that hook.

docs/docs/how-to-install.md

@@ -25,11 +25,12 @@ If your project uses Apollo Client 4, make sure `rxjs` `^7.3.0` is installed as
 
 ## Loading the Laika Link in your project
 
-For tests that run on your production code, you'll likely want to load the link conditionally, so that it is not downloaded by your users, but only in certain scenarios, e.g. inside of your browser test runner.
+For tests that run on your production code, you'll likely want to load the link conditionally, so that it is not downloaded by your users, but only in certain scenarios, such as inside of your browser test runner.
 
-Include the link wherever you like in your chain of links, however we recommend putting it right before the connection with the backend occurs for most accurate results.
+Include the link wherever you like in your chain of links. We recommend putting it right before the connection with the backend occurs for the most accurate results.
 
-```js
+```ts
+import { ApolloClient, ApolloLink, HttpLink } from '@apollo/client'
 import { createLazyLoadableLaikaLink } from '@zendesk/laika'
 
 const apolloClient = new ApolloClient({
@@ -49,58 +50,110 @@ const apolloClient = new ApolloClient({
 })
 ```
 
-### Customizing loading of the Link
+### Customizing loading of the link
 
-By default, link is lazily loaded and if you use webpack, split into a seaprate chunk by utilizing the `createLazyLoadableLink` function provided in the package.
+By default, the link is lazily loaded and, if you use webpack, split into a separate chunk by utilizing the `createLazyLoadableLink` function provided in the package.
 
 You may customize this behavior. This is the default behavior:
 
-```js
+```ts
 import { createLazyLoadableLink } from '@zendesk/laika'
 
 /**
  * @param {{clientName: string}} options
  */
 export const createLazyLoadableLaikaLink = (options) =>
   createLazyLoadableLink(
-    import('@zendesk/laika' /* webpackChunkName: 'apolloLaikaLink' */).then(
-      ({ createInterceptingLink }) => createInterceptingLink(options),
-    ),
+    import(
+      '@zendesk/laika/createGlobalLaikaLink' /* webpackChunkName: 'apolloLaikaLink' */
+    ).then(({ createGlobalLaikaLink }) => createGlobalLaikaLink(options)),
   )
 ```
 
-If you're using webpack, the `webpackChunkName` magic comment will ensure a separate chunk is file created for the link.
+If you're using webpack, the `webpackChunkName` magic comment will ensure a separate chunk is created for the link.
 
-## Loading the Link in unit tests
+## Conditionally enabling Laika
 
-If you have full control over the Apollo client inside of your tests, you may directly create the Link from an instance of Laika:
+Most apps should enable Laika only for specific environments, developers, or test sessions.
 
-```typescript
+Common patterns include:
+
+- a build-time flag such as `NODE_ENV !== 'production'`
+- a query parameter such as `?laika=1` or `?e2e=true`
+- a test-only browser hook that your Playwright or Cypress suite opts into
+
+For complete examples, see [Conditionally loading Laika](pathname:///docs/loading-laika-conditionally).
+
+## Browser E2E runners
+
+When you need to intercept requests that fire during the initial page render, register callbacks on `window.laikaReadyCallbacks` before the app code executes.
+
+Use:
+
+- [Usage in Playwright](pathname:///docs/usage-in-playwright) for `page.addInitScript()` / `browserContext.addInitScript()`
+- [Usage in Cypress](pathname:///docs/usage-in-cypress) for `cy.visit(..., { onBeforeLoad })`
+
+If you already know your app only enables Laika behind a query parameter, make sure your test navigates with that flag enabled as well.
+
+## Loading the link in unit tests
+
+If you have full control over the Apollo client inside of your tests, you may directly create the link from an instance of Laika:
+
+```ts
+import {
+  ApolloClient,
+  ApolloLink,
+  InMemoryCache,
+  Observable,
+  gql,
+} from '@apollo/client'
 import { Laika } from '@zendesk/laika/esm/laika'
 
 const laika = new Laika()
 
-const link = from([laika.createLink(), new HttpLink({ uri: '...' })])
+const terminatingLink = new ApolloLink(
+  () =>
+    new Observable((observer) => {
+      observer.next?.({ data: { healthy: true } })
+      observer.complete?.()
+    }),
+)
+
+const client = new ApolloClient({
+  cache: new InMemoryCache(),
+  link: ApolloLink.from([laika.createLink(), terminatingLink]),
+})
 
 afterEach(() => {
   laika.mockRestoreAll()
 })
 
-it('works', () => {
-  // setup your test, for example:
+it('works', async () => {
   const interceptor = laika.intercept()
   interceptor.mockResultOnce({
     result: {
       data: {
-        /* ... */
+        healthy: false,
       },
     },
   })
-  // run some assertions
-  // ...
+
+  await expect(
+    client.query({
+      query: gql`
+        query Healthcheck {
+          healthy
+        }
+      `,
+    }),
+  ).resolves.toMatchObject({
+    data: { healthy: false },
+  })
 })
 ```
 
+For a more complete unit-testing guide, see [Usage in Jest / Vitest](pathname:///docs/usage-in-jest-vitest).
+
 Note that Laika itself isn't directly exported from `@zendesk/laika` in order to minimize the amount of data that is bundled with your application when using lazily loaded Laika in production.
 
 If your test runner reuses the same page or process across tests, call `laika.mockRestoreAll()` in `afterEach` to clear all interceptors before the next scenario starts. See [Resetting Between Tests](pathname:///docs/resetting-between-tests).
@@ -111,4 +164,6 @@ See the [API reference](pathname:///docs/api).
 
 ## What next?
 
-Read about how to use the library in [Laika](pathname:///docs/api/interfaces/Laika).
+If you're deciding where Laika should sit in your test strategy, start with [Testing approach](pathname:///docs/testing-approach).
+
+For advanced matcher, lifecycle, and passthrough patterns, see [Advanced usage](pathname:///docs/advanced-usage).