kinde-testkit 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +235 -11
- package/dist/cli.js +2160 -267
- package/dist/cypress-support.d.ts +98 -0
- package/dist/cypress-support.js +119 -0
- package/dist/cypress-support.js.map +1 -0
- package/dist/cypress.cjs +4249 -0
- package/dist/cypress.cjs.map +1 -0
- package/dist/cypress.d.cts +118 -0
- package/dist/cypress.d.ts +118 -0
- package/dist/cypress.js +3324 -0
- package/dist/cypress.js.map +1 -0
- package/dist/index.cjs +3270 -314
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +326 -2
- package/dist/index.d.ts +326 -2
- package/dist/index.js +1954 -150
- package/dist/index.js.map +1 -1
- package/dist/jest.cjs +4318 -0
- package/dist/jest.cjs.map +1 -0
- package/dist/jest.d.cts +567 -0
- package/dist/jest.d.ts +567 -0
- package/dist/jest.js +3392 -0
- package/dist/jest.js.map +1 -0
- package/dist/vitest.d.ts +236 -1
- package/dist/vitest.js +1853 -155
- package/dist/vitest.js.map +1 -1
- package/package.json +36 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
- Add `kinde-testkit/jest` with the same `useKindeTestkit()` and `kindeTest()` as the Vitest helper, for CommonJS and ESM test files.
|
|
6
|
+
- Add Cypress support: `setupKindeTestkit()` starts the testkit from `setupNodeEvents`, and `kinde-testkit/cypress/support` adds `cy.kindeSignIn()`, `cy.kindeSignOut()`, `cy.kindeToken()`, `cy.kindeInjectFailure()`, `cy.kindeClearFailures()`, `cy.kindeSendWebhook()` and `cy.kindeReset()`.
|
|
7
|
+
- Load seed files in YAML, JavaScript and TypeScript as well as JSON, and replace a running issuer's seed with `kinde-testkit seed <file>`.
|
|
8
|
+
- Add a dashboard at `/dashboard` with the seed, recent tokens, requests, webhook deliveries, failure rules and coverage, plus reset and send forms.
|
|
9
|
+
- Add an authentication coverage report: the testkit records which identity, organization, permission, token, session, M2M, API, webhook and outage cases a run produced. Read it with `kinde-testkit coverage`, and fail CI below a number with `--min`.
|
|
10
|
+
- Add a Dockerfile that runs the issuer as a non-root user with a health check, plus Docker Compose instructions.
|
|
11
|
+
- The Next.js example adds Cypress tests.
|
|
12
|
+
|
|
13
|
+
## 0.5.0
|
|
14
|
+
|
|
15
|
+
- Add the Management API at `/api/v1`: users, organizations, organization members, member roles and permissions, roles and permissions. It needs an M2M token for `<issuer>/api`, checks the scopes of seeded applications, and writes every change into the testkit's data. Changes send the matching webhooks. Unimplemented routes answer 404 `ROUTE_NOT_FOUND`.
|
|
16
|
+
- Add the Account API at `/account_api/v1`: permissions, roles, feature flags, properties, entitlements and the portal link, for the active organization of the user's token. Kinde's `@kinde/js-utils` helpers work against it.
|
|
17
|
+
- Add HTTPS mode (`https: true`, `start --https`, `kinde-testkit cert`) with a local certificate, so Kinde's official `@kinde/management-api-js` client runs unchanged. CLI commands given an `https://` URL trust the certificate on their own.
|
|
18
|
+
- The seed takes `roles` with permissions, `permissions`, `featureFlags` with organization values, `plans` with entitlements, and user `properties`. A role's permissions are added to the member's token. Feature flags go into access tokens.
|
|
19
|
+
- Suspended users cannot sign in, and `reset()` restores the seed after API changes.
|
|
20
|
+
|
|
3
21
|
## 0.4.0
|
|
4
22
|
|
|
5
23
|
- Add signed webhooks in Kinde's format: a JWT body with `Content-Type: application/jwt` and a `webhook-id` header, decodable with `@kinde/webhooks`.
|
package/README.md
CHANGED
|
@@ -7,9 +7,9 @@ Test apps that use Kinde without a live Kinde environment. kinde-testkit runs a
|
|
|
7
7
|
There are two ways to use it:
|
|
8
8
|
|
|
9
9
|
- **API and unit tests:** mint a token for any user, organization and permission set, including expired, tampered and unsigned tokens, and send it to your API.
|
|
10
|
-
- **Browser tests:** point your app at the testkit, and Playwright signs in as any seeded user through your app's own login route.
|
|
10
|
+
- **Browser tests:** point your app at the testkit, and Playwright or Cypress signs in as any seeded user through your app's own login route.
|
|
11
11
|
|
|
12
|
-
It also issues machine-to-machine tokens, sends signed webhooks, makes Kinde's endpoints fail or slow down on demand
|
|
12
|
+
It also issues machine-to-machine tokens, answers the Management API and Account API calls your app makes, sends signed webhooks, and makes Kinde's endpoints fail or slow down on demand. A local dashboard shows what the testkit issued and answered, a coverage report shows which authentication cases your tests reached, and a `doctor` command checks your app's Kinde settings before a test run. It runs with Vitest, Jest, Playwright and Cypress, from the command line, or in Docker.
|
|
13
13
|
|
|
14
14
|
## Why it exists
|
|
15
15
|
|
|
@@ -85,6 +85,25 @@ describe("projects API", () => {
|
|
|
85
85
|
|
|
86
86
|
`useKindeTestkit()` starts the issuer on a free port before the tests and stops it after. Point your app's issuer setting at `kinde.issuer` for the test run, so its middleware fetches keys from the testkit instead of Kinde.
|
|
87
87
|
|
|
88
|
+
### Jest
|
|
89
|
+
|
|
90
|
+
`kinde-testkit/jest` has the same `useKindeTestkit()` and `kindeTest()`. It works with CommonJS and ESM test files:
|
|
91
|
+
|
|
92
|
+
```js
|
|
93
|
+
const { scenario } = require("kinde-testkit");
|
|
94
|
+
const { useKindeTestkit } = require("kinde-testkit/jest");
|
|
95
|
+
|
|
96
|
+
const kinde = useKindeTestkit({ seed: "kinde-testkit.yaml" });
|
|
97
|
+
|
|
98
|
+
test("a viewer cannot delete a project", async () => {
|
|
99
|
+
const { headers } = await kinde.auth(scenario().user({ email: "viewer@example.test" }).organization("org_acme").authenticated());
|
|
100
|
+
const res = await request(app).delete("/projects/p1").set(headers);
|
|
101
|
+
expect(res.status).toBe(403);
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
It uses Jest's global `beforeAll` and `afterAll`. If you turn off `injectGlobals`, pass them from `@jest/globals`: `useKindeTestkit(options, { beforeAll, afterAll })`.
|
|
106
|
+
|
|
88
107
|
## Browser tests with Playwright
|
|
89
108
|
|
|
90
109
|
Start the testkit and your app from `playwright.config.ts`, with the app's Kinde settings pointed at the testkit:
|
|
@@ -155,6 +174,52 @@ A user with more than one organization needs `{ org }`, otherwise the fixture st
|
|
|
155
174
|
|
|
156
175
|
[`examples/nextjs`](examples/nextjs) is a working Next.js app on `@kinde-oss/kinde-auth-nextjs` with these tests.
|
|
157
176
|
|
|
177
|
+
## Browser tests with Cypress
|
|
178
|
+
|
|
179
|
+
Start the testkit from `setupNodeEvents`, and import the commands in your support file:
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
// cypress.config.ts
|
|
183
|
+
import { defineConfig } from "cypress";
|
|
184
|
+
import { setupKindeTestkit } from "kinde-testkit/cypress";
|
|
185
|
+
|
|
186
|
+
export default defineConfig({
|
|
187
|
+
e2e: {
|
|
188
|
+
baseUrl: "http://localhost:3000",
|
|
189
|
+
setupNodeEvents(on, config) {
|
|
190
|
+
return setupKindeTestkit(on, config, { start: { seed: "kinde-testkit.json" } });
|
|
191
|
+
},
|
|
192
|
+
},
|
|
193
|
+
});
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
// cypress/support/e2e.ts
|
|
198
|
+
import "kinde-testkit/cypress/support";
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
This starts the testkit on port 4400 for the run, so start your app with `KINDE_ISSUER_URL=http://localhost:4400`. If you already run `kinde-testkit start`, leave out `start`, and the commands use `KINDE_ISSUER_URL` or `http://localhost:4400`.
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
it("a viewer cannot delete projects", () => {
|
|
205
|
+
cy.kindeSignIn("viewer@example.test");
|
|
206
|
+
cy.visit("/projects");
|
|
207
|
+
cy.contains("button", /Delete/).should("not.exist");
|
|
208
|
+
});
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
| Command | What it does |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| `cy.kindeSignIn(email, { org, loginPath })` | Signs in through your app's login route with requests, then opens the app's callback. Fast, and needs no `cy.origin()` |
|
|
214
|
+
| `cy.kindeSignOut({ logoutPath })` | Opens your app's logout route |
|
|
215
|
+
| `cy.kindeToken(options)` | Yields an access token, with the same options as `POST /testkit/token` |
|
|
216
|
+
| `cy.kindeInjectFailure(rule)` | Makes a testkit endpoint fail, slow down or hang. Removed when the test ends |
|
|
217
|
+
| `cy.kindeClearFailures()` | Removes the failures this test added |
|
|
218
|
+
| `cy.kindeSendWebhook(event)` | Sends a signed webhook and yields the delivery results |
|
|
219
|
+
| `cy.kindeReset()` | Clears sessions, failure rules, deliveries and Management API changes |
|
|
220
|
+
|
|
221
|
+
`cy.kindeSignIn()` skips the sign-in page but runs everything else your app does: its login route, its state cookie and its callback, where the app exchanges the code for tokens. To test the sign-in page itself, visit your login route and use `cy.origin("http://localhost:4400", ...)`. The example app's `cypress/e2e/auth.cy.ts` does both.
|
|
222
|
+
|
|
158
223
|
### The sign-in page
|
|
159
224
|
|
|
160
225
|
The page at `/oauth2/auth` lists the seeded users. You can also type any email address: a user that is not in the seed file signs in without an organization. A user with more than one organization picks one on the next screen, unless the app sent `org_code`.
|
|
@@ -238,6 +303,49 @@ These options test the hard parts of a webhook handler:
|
|
|
238
303
|
|
|
239
304
|
`kinde.webhooks.deliveries()`, `kinde-testkit webhook --deliveries` and `GET /testkit/webhooks/deliveries` show every attempt with its status code or error. [`examples/nextjs`](examples/nextjs) has a webhook route and Playwright tests for valid, duplicated, forged and stale events.
|
|
240
305
|
|
|
306
|
+
## Management API and Account API
|
|
307
|
+
|
|
308
|
+
Many apps call Kinde's APIs as well as signing users in. An admin page creates organizations and adds members, a signup flow creates users, and the front end asks the Account API for the current user's permissions and feature flags. kinde-testkit answers these calls from the seed, so the test checks what your code does with the result.
|
|
309
|
+
|
|
310
|
+
The Management API is at `/api/v1`. Like Kinde, it needs a machine-to-machine token for the audience `<issuer>/api`. When a seeded application has scopes, the token gets those scopes and each route checks for its own, such as `read:users` or `create:organizations`. These routes work:
|
|
311
|
+
|
|
312
|
+
| Area | Routes |
|
|
313
|
+
| --- | --- |
|
|
314
|
+
| Users | List, filter by ID or email, get, create, update (including `is_suspended`), delete |
|
|
315
|
+
| Organizations | List, get, create, update, delete |
|
|
316
|
+
| Members | List, add with roles, remove |
|
|
317
|
+
| Member roles and permissions | List, grant, remove |
|
|
318
|
+
| Roles and permissions | List, get, create, delete, and list a role's permissions |
|
|
319
|
+
|
|
320
|
+
Every change goes into the testkit's data. A user you create can sign in, a member you add gets the role's permissions in their next token, and a suspended user sees an error on the sign-in page. Each change also sends the matching webhook, such as `organization.created` or `user.deleted`, to your configured endpoints. `reset()` puts the seed back. A route the testkit does not implement answers 404 with the code `ROUTE_NOT_FOUND`, so a test never passes against an empty answer.
|
|
321
|
+
|
|
322
|
+
Kinde's official client, `@kinde/management-api-js`, forces `https://`. Start the testkit with HTTPS and run your code with the certificate it prints:
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
const kinde = useKindeTestkit({ seed, https: true });
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
```bash
|
|
329
|
+
npx kinde-testkit start --https
|
|
330
|
+
NODE_EXTRA_CA_CERTS=.kinde-testkit/localhost-cert.pem npm test
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
The first start writes a self-signed certificate for `localhost` and `127.0.0.1` to `.kinde-testkit/` and reuses it after that. The test suite runs the official client against the testkit without changes.
|
|
334
|
+
|
|
335
|
+
The Account API is at `/account_api/v1`. It reads the user's access token and answers for the token's active organization: `permissions`, `permission/<key>`, `roles`, `feature_flags`, `properties`, `entitlements`, `entitlement/<key>` and `portal_link`. Kinde's `@kinde/js-utils` helpers, such as `getPermissions({ forceApi: true })`, `getFlag()` and `getEntitlements()`, work against it. Add the data it returns to the seed:
|
|
336
|
+
|
|
337
|
+
```json
|
|
338
|
+
{
|
|
339
|
+
"users": [{ "id": "kp_admin", "email": "admin@example.test", "properties": { "team": "platform" } }],
|
|
340
|
+
"roles": [{ "key": "admin", "name": "Admin", "permissions": ["projects:read", "projects:delete"] }],
|
|
341
|
+
"memberships": [{ "user": "kp_admin", "organization": "org_acme", "roles": ["admin"] }],
|
|
342
|
+
"featureFlags": [{ "key": "new_editor", "value": false, "organizations": { "org_acme": true } }],
|
|
343
|
+
"plans": [{ "key": "pro", "subscribers": ["org_acme"], "entitlements": [{ "featureKey": "seats", "limitMax": 10 }] }]
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
A role's permissions are added to the member's own permissions, in tokens and in both APIs. Feature flags also go into access tokens as `feature_flags`, with the organization's value when it has one.
|
|
348
|
+
|
|
241
349
|
## Testing outages
|
|
242
350
|
|
|
243
351
|
Your app should handle Kinde being slow or down. kinde-testkit can make any endpoint answer with an error, wait before answering, or never answer:
|
|
@@ -331,6 +439,7 @@ Issuer: http://localhost:4400
|
|
|
331
439
|
Discovery: http://localhost:4400/.well-known/openid-configuration
|
|
332
440
|
JWKS: http://localhost:4400/.well-known/jwks
|
|
333
441
|
Token: POST http://localhost:4400/testkit/token
|
|
442
|
+
Dashboard: http://localhost:4400/dashboard
|
|
334
443
|
```
|
|
335
444
|
|
|
336
445
|
Then mint a token from another terminal:
|
|
@@ -342,7 +451,23 @@ curl -H "Authorization: Bearer $(npx kinde-testkit token --user admin@example.te
|
|
|
342
451
|
|
|
343
452
|
### Seed file
|
|
344
453
|
|
|
345
|
-
|
|
454
|
+
`start` loads the first of `kinde-testkit.json`, `.yaml`, `.yml`, `.ts`, `.mts`, `.js` and `.mjs` in the current folder. Pass `--seed <file>` to use another path. In code, `seed` takes an object or a file path. The same seed in YAML:
|
|
455
|
+
|
|
456
|
+
```yaml
|
|
457
|
+
users:
|
|
458
|
+
- id: kp_admin
|
|
459
|
+
email: admin@example.test
|
|
460
|
+
organizations:
|
|
461
|
+
- code: org_acme
|
|
462
|
+
name: Acme Inc.
|
|
463
|
+
memberships:
|
|
464
|
+
- user: kp_admin
|
|
465
|
+
organization: org_acme
|
|
466
|
+
roles: [admin]
|
|
467
|
+
permissions: [projects:read, projects:delete]
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
A JavaScript or TypeScript seed exports the object as its default export or as `seed`. TypeScript seeds need Node 22.18 or later, which runs TypeScript files directly. The JSON version, with every section:
|
|
346
471
|
|
|
347
472
|
```json
|
|
348
473
|
{
|
|
@@ -371,19 +496,100 @@ When `kinde-testkit.json` exists in the current folder, `start` loads it. Pass `
|
|
|
371
496
|
|
|
372
497
|
A token for a seeded user takes its roles and permissions from the membership in the active organization. A user with two memberships must name the organization. The issuer refuses a token for an organization the user does not belong to, because Kinde would not issue one. The issuer checks the whole seed when it starts and lists every problem at once.
|
|
373
498
|
|
|
499
|
+
`kinde-testkit seed <file>` replaces the seed of a running issuer, and `reset` returns to that seed after that. The issuer, audience and signing key stay the same, so apps that cached the keys keep working. `kinde-testkit stop` stops a running issuer.
|
|
500
|
+
|
|
501
|
+
## Dashboard
|
|
502
|
+
|
|
503
|
+
Open `http://localhost:4400/dashboard` while the testkit runs. It shows:
|
|
504
|
+
|
|
505
|
+
- users, organizations and memberships, with the permissions each member's token gets
|
|
506
|
+
- the latest tokens the testkit issued, with their claims
|
|
507
|
+
- the latest requests to Kinde's endpoints, with status and time taken. Codes, secrets and refresh tokens are hidden
|
|
508
|
+
- webhook deliveries, and a form to send an event
|
|
509
|
+
- failure rules, and a form to add one
|
|
510
|
+
- the coverage report
|
|
511
|
+
|
|
512
|
+
It has buttons to reset the testkit and to clear coverage. **Live updates** reloads the page every 3 seconds. The dashboard only adds a view: everything on it is also in the CLI and the HTTP endpoints. It only accepts actions from its own page, so another site you have open cannot reset or change the testkit.
|
|
513
|
+
|
|
514
|
+
## Authentication coverage
|
|
515
|
+
|
|
516
|
+
Most suites test that a user can sign in. Authorization bugs hide in the other cases: a token from another organization, an expired token, a user with no permissions. The testkit records which of these cases it produced during a run, grouped the way the bugs happen:
|
|
517
|
+
|
|
518
|
+
```bash
|
|
519
|
+
npx kinde-testkit coverage
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
```
|
|
523
|
+
Kinde authentication coverage
|
|
524
|
+
|
|
525
|
+
Identity 6/6
|
|
526
|
+
Organizations 4/5
|
|
527
|
+
Permissions 5/5
|
|
528
|
+
Token validation 3/8
|
|
529
|
+
Sessions 4/5
|
|
530
|
+
Machine-to-machine 0/4
|
|
531
|
+
Kinde APIs 2/4
|
|
532
|
+
Webhooks 5/5
|
|
533
|
+
Outages 2/4
|
|
534
|
+
|
|
535
|
+
Overall: 31/46
|
|
536
|
+
|
|
537
|
+
Not covered:
|
|
538
|
+
Organizations: Organization claim missing. Mint a token with invalid: "missing-organization".
|
|
539
|
+
Token validation: Wrong issuer. Mint a token with invalid: "wrong-issuer".
|
|
540
|
+
...
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
Turn it on with `useKindeTestkit({ coverage: true })` in Vitest or Jest, `setupKindeTestkit(on, config, { start: { coverage: true } })` in Cypress, or `kinde-testkit start --coverage`. Each test file writes its result to `.kinde-testkit/coverage/` when it ends, and `kinde-testkit coverage` adds them up. Clear the folder before a run with `kinde-testkit coverage --clear`, and fail CI below a number with `--min 30`. For a running issuer, `kinde-testkit coverage --url http://localhost:4400` reads it directly, and the dashboard shows the same report.
|
|
544
|
+
|
|
545
|
+
Coverage counts what the testkit produced, such as an expired token or a 503 from the token endpoint. It does not know what your test checked after that. A covered item means your suite sent that case to your app. Your assertions decide whether the app handled it.
|
|
546
|
+
|
|
547
|
+
## Docker
|
|
548
|
+
|
|
549
|
+
The repository has a Dockerfile. Build it straight from GitHub, then mount the folder with your seed file:
|
|
550
|
+
|
|
551
|
+
```bash
|
|
552
|
+
docker build -t kinde-testkit https://github.com/sholajegede/kinde-testkit.git
|
|
553
|
+
docker run --rm -p 4400:4400 -v "$PWD:/work" kinde-testkit
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
The container runs `kinde-testkit start` as a non-root user, loads the seed file from `/work`, and has a health check on `/testkit/health`. Its issuer is `http://localhost:4400`, which is right when your app and browser run on the host. In Docker Compose, where the app reaches the testkit by service name, set the issuer to the address your app uses:
|
|
557
|
+
|
|
558
|
+
```yaml
|
|
559
|
+
services:
|
|
560
|
+
kinde:
|
|
561
|
+
build: https://github.com/sholajegede/kinde-testkit.git
|
|
562
|
+
command: ["start", "--host", "0.0.0.0", "--port", "4400", "--allow-public", "--issuer", "http://kinde:4400"]
|
|
563
|
+
volumes: ["./:/work"]
|
|
564
|
+
app:
|
|
565
|
+
build: .
|
|
566
|
+
environment:
|
|
567
|
+
KINDE_ISSUER_URL: http://kinde:4400
|
|
568
|
+
depends_on:
|
|
569
|
+
kinde:
|
|
570
|
+
condition: service_healthy
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
The browser must reach the same issuer address as the app, because the issuer in the token has to match. Run browser tests on the host with the `localhost` setup, or run the browser in the same Compose network.
|
|
574
|
+
|
|
374
575
|
### Commands
|
|
375
576
|
|
|
376
577
|
| Command | What it does |
|
|
377
578
|
| --- | --- |
|
|
378
|
-
| `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--allow-public`, `--json` |
|
|
579
|
+
| `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--https`, `--cert-dir`, `--coverage`, `--allow-public`, `--json` |
|
|
580
|
+
| `kinde-testkit stop` | Stop a running issuer. Options: `--url` |
|
|
581
|
+
| `kinde-testkit seed <file>` | Replace a running issuer's seed with a JSON, YAML, JavaScript or TypeScript file. Options: `--url`, `--json` |
|
|
582
|
+
| `kinde-testkit cert` | Write the local HTTPS certificate and print the `NODE_EXTRA_CA_CERTS` line. Options: `--dir` |
|
|
379
583
|
| `kinde-testkit token` | Print a signed access token. Options: `--user`, `--org`, `--sub`, `--permissions`, `--roles`, `--expires-in`, `--invalid`, `--url`, `--json` |
|
|
380
584
|
| `kinde-testkit users` | List seeded users |
|
|
381
585
|
| `kinde-testkit organizations` | List seeded organizations |
|
|
382
586
|
| `kinde-testkit token --m2m` | Print a machine-to-machine token. Options: `--client-id`, `--scope`, `--org`, `--permissions`, `--expires-in`, `--invalid` |
|
|
383
587
|
| `kinde-testkit inspect [token]` | Decode a token and check it. Reads stdin when no token is given. Options: `--url`, `--json` |
|
|
588
|
+
| `kinde-testkit inspect --requests` | List the latest requests the issuer answered. `--tokens` lists the latest tokens it issued |
|
|
589
|
+
| `kinde-testkit coverage` | Show which authentication cases your tests covered. Options: `--url`, `--dir`, `--min`, `--clear`, `--json` |
|
|
384
590
|
| `kinde-testkit doctor` | Check your app's Kinde settings against the issuer. Options: `--url`, `--env-file`, `--json` |
|
|
385
591
|
| `kinde-testkit fail <path>` | Add a failure rule. Options: `--status`, `--delay`, `--hang`, `--times`, `--method`, `--list`, `--clear` |
|
|
386
|
-
| `kinde-testkit reset` | Clear sign-in sessions, failure rules, webhook deliveries
|
|
592
|
+
| `kinde-testkit reset` | Clear sign-in sessions, failure rules, webhook deliveries, endpoints added at runtime and Management API changes |
|
|
387
593
|
| `kinde-testkit webhook <type>` | Send a signed webhook. Options: `--user`, `--org`, `--role`, `--permission`, `--data`, `--to`, `--duplicate`, `--invalid`, `--types`, `--deliveries` |
|
|
388
594
|
|
|
389
595
|
Every command takes `--json` for CI scripts and coding agents.
|
|
@@ -425,12 +631,16 @@ import {
|
|
|
425
631
|
- `scenario()` builds a caller: `.user()`, `.organization()`, `.withoutOrganization()`, `.role()`, `.permissions()`, `.claims()`, then `.authenticated()` or `.unauthenticated()`. The result is plain JSON, so you can keep scenarios in a shared file and import them anywhere.
|
|
426
632
|
- `createKindeUser()` gives a user a stable id derived from the email, so the same email always maps to the same `kp_` id. `createKindeOrganization()` and `createMembership()` cover organizations and per-organization roles.
|
|
427
633
|
- `KindeTestkit.create({ issuer, audience, clientId, accessTokenExpiresIn, idTokenExpiresIn })` holds a signing key. Access tokens last 24 hours and ID tokens 1 hour by default, the same as Kinde's defaults. Use `token()`, `tokenFor(scenario)`, `idTokenFor(scenario)`, `m2mToken()`, `headersFor(scenario)`, `principalFor(scenario)`, `signPayload()` and `jwks()`.
|
|
428
|
-
- `startKindeTestkit({ port, seed, audience })` runs the issuer in-process and returns `{ url, issuer, jwksUri, testkit, failures, webhooks, reset(), close() }`. Pass `webhooks: { retryDelaysMs, timeoutMs }` to change webhook retries.
|
|
634
|
+
- `startKindeTestkit({ port, seed, audience, https, coverage })` runs the issuer in-process and returns `{ url, issuer, jwksUri, testkit, failures, webhooks, directory, coverage, activity, loadSeed(), reset(), close() }`. `seed` is an object or a file path. Pass `webhooks: { retryDelaysMs, timeoutMs }` to change webhook retries.
|
|
635
|
+
- `loadSeedFile(path)` reads a JSON, YAML, JavaScript or TypeScript seed. `readCoverageDirectory()`, `formatCoverageReport()` and `CoverageRecorder` are the functions behind `kinde-testkit coverage`.
|
|
636
|
+
- `appLoginUrl()`, `readSignInRequest()`, `signInForm()` and `resolveLocation()` are the steps `cy.kindeSignIn()` takes, for signing in with requests from another test runner.
|
|
429
637
|
- `inspectToken(token, { issuerUrl })` and `runDoctor({ url, env })` are the functions behind `inspect` and `doctor`. Both return a list of checks with `pass`, `warn` or `fail`.
|
|
430
638
|
- `createKindeToken(options)` signs with a shared default testkit whose issuer is `http://localhost:4400`, or `KINDE_TESTKIT_ISSUER` when set.
|
|
431
639
|
- `principalFromClaims(claims)` turns verified claims into `{ type, subject, issuer, organization, roles, permissions }`. `type` is `"user"`, or `"machine"` for M2M tokens.
|
|
432
640
|
|
|
433
|
-
From `kinde-testkit/vitest`: `useKindeTestkit()`, which also exposes `failures`, `webhooks` and `reset()`, and `kindeTest()`.
|
|
641
|
+
From `kinde-testkit/vitest` and `kinde-testkit/jest`: `useKindeTestkit()`, which also exposes `failures`, `webhooks`, `directory`, `coverage`, `activity`, `loadSeed()` and `reset()`, and `kindeTest()`.
|
|
642
|
+
|
|
643
|
+
From `kinde-testkit/cypress`: `setupKindeTestkit(on, config, { start, url })`. From `kinde-testkit/cypress/support`: the `cy.kinde*` commands and their types.
|
|
434
644
|
|
|
435
645
|
From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, the `KindeTestOptions` type for your config, and `createKindeFixture(page, options)` for building the fixture into your own `test.extend()`.
|
|
436
646
|
|
|
@@ -445,13 +655,20 @@ From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, t
|
|
|
445
655
|
| `GET /oauth2/v2/user_profile` | Profile for the Bearer token's user |
|
|
446
656
|
| `POST /oauth2/revoke` | Revokes a refresh token |
|
|
447
657
|
| `GET /logout?redirect=<url>` | Signs out and redirects |
|
|
658
|
+
| `/api/v1/...` | Management API: users, organizations, members, roles and permissions |
|
|
659
|
+
| `GET /account_api/v1/...` | Account API: permissions, roles, feature flags, properties and entitlements for the token's user |
|
|
448
660
|
| `POST /testkit/token` | Mints a token directly, used by `kinde-testkit token` |
|
|
449
661
|
| `GET /testkit/users`, `/testkit/organizations`, `/testkit/memberships`, `/testkit/health` | Seed data and a health check |
|
|
450
662
|
| `GET`, `POST`, `DELETE /testkit/failures`, `DELETE /testkit/failures/<id>` | List, add and remove failure rules |
|
|
451
663
|
| `POST /testkit/webhooks` | Send a webhook and return the deliveries |
|
|
452
664
|
| `GET /testkit/webhooks/deliveries`, `/testkit/webhooks/types` | Delivery log and the event types with built-in payloads |
|
|
453
665
|
| `GET`, `POST /testkit/webhooks/endpoints`, `DELETE /testkit/webhooks/endpoints/<id>` | List, add and remove webhook endpoints |
|
|
454
|
-
| `POST /testkit/reset` | Clear sign-in state, failure rules
|
|
666
|
+
| `POST /testkit/reset` | Clear sign-in state, failure rules, webhook deliveries and Management API changes |
|
|
667
|
+
| `POST /testkit/seed` | Replace the seed with the JSON body |
|
|
668
|
+
| `POST /testkit/stop` | Stop the issuer |
|
|
669
|
+
| `GET`, `DELETE /testkit/coverage` | Read or clear the coverage report |
|
|
670
|
+
| `GET /testkit/requests`, `/testkit/tokens` | The latest requests answered and tokens issued |
|
|
671
|
+
| `GET /dashboard` | The dashboard |
|
|
455
672
|
|
|
456
673
|
## Token shape
|
|
457
674
|
|
|
@@ -492,20 +709,27 @@ ID tokens carry `amr`, `aud` (the client ID), `auth_time`, `email`, `email_verif
|
|
|
492
709
|
| Switching the active organization | Implemented through `org_code` or the organization picker |
|
|
493
710
|
| Authorization code flow with sign-in page, PKCE and `state` | Implemented |
|
|
494
711
|
| Refresh tokens with rotation, revocation, logout and user profile | Implemented |
|
|
495
|
-
| Vitest
|
|
712
|
+
| Vitest and Jest helpers, Playwright fixture, Cypress commands | Implemented. Jest runs in the test suite. Cypress's sign-in steps are tested against the Next.js SDK |
|
|
496
713
|
| Accepted by `@kinde/jwt-validator` and the Next.js SDK's `validateToken` | Tested |
|
|
497
714
|
| Sign-in, organization switching and sign-out through `@kinde-oss/kinde-auth-nextjs` | Tested in Chrome with Playwright |
|
|
498
715
|
| Client credentials grant with Kinde's M2M token shape, seeded and org-scoped apps | Implemented |
|
|
499
716
|
| Failure injection: error status, delay, hang, by path, method and count | Implemented, tested through the Next.js SDK |
|
|
500
717
|
| `doctor`, `inspect` and `reset` commands | Implemented |
|
|
501
|
-
| Management API and
|
|
718
|
+
| Management API: users, organizations, members, roles and permissions | Implemented, tested with `@kinde/management-api-js` |
|
|
719
|
+
| Account API: permissions, roles, feature flags, properties and entitlements | Implemented, tested with `@kinde/js-utils` |
|
|
720
|
+
| Seed files in JSON, YAML, JavaScript and TypeScript, replaced at runtime | Implemented |
|
|
721
|
+
| Dashboard, request and token log | Implemented |
|
|
722
|
+
| Authentication coverage report | Implemented |
|
|
723
|
+
| Docker image | Dockerfile in the repository |
|
|
724
|
+
| Passwords, MFA, social sign-in and SAML | Not emulated. The sign-in page signs in any seeded user or email directly |
|
|
725
|
+
| Kinde's hosted pages, such as the self-serve portal | Not emulated. `portal_link` returns a placeholder page |
|
|
502
726
|
| Signed webhooks for the 16 event types in `@kinde/webhooks`, billing events with your data, retries, duplicates, forged and stale events | Implemented, tested with `@kinde/webhooks` and a Next.js route |
|
|
503
727
|
|
|
504
728
|
## Safety
|
|
505
729
|
|
|
506
730
|
kinde-testkit signs a token for any identity you ask for, so it keeps to localhost:
|
|
507
731
|
|
|
508
|
-
- The issuer binds to `127.0.0.1` and refuses any other interface unless you pass `--allow-public`.
|
|
732
|
+
- The issuer binds to `127.0.0.1` and refuses any other interface unless you pass `--allow-public`. The Docker image passes it, because the container's own network is where it listens. Publish the port to your machine only, as `-p 4400:4400` does.
|
|
509
733
|
- It makes a new signing key every time it starts. Two running issuers never share a key.
|
|
510
734
|
- It accepts any client ID, client secret and redirect URI, so it never needs your real app settings. That is only safe because it stays on localhost.
|
|
511
735
|
- Codes, refresh tokens and users who sign in with an unseeded email live in memory and are gone when it stops.
|