@nocobase/app-skills 0.1.0-beta.37 → 0.1.0-beta.39
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/package.json +1 -1
- package/skills/nocobase-app-development/SKILL.md +23 -7
- package/skills/nocobase-app-development/references/app-structure.md +4 -0
- package/skills/nocobase-app-development/references/frontend/references/page.md +6 -0
- package/skills/nocobase-app-development/references/frontend/references/testing.md +11 -59
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +28 -1
- package/skills/nocobase-app-development/references/lifecycle-parameters.md +10 -4
- package/skills/nocobase-app-development/references/lifecycle-ui.md +122 -0
- package/skills/nocobase-app-development/references/lifecycle.md +9 -5
- package/skills/nocobase-app-development/references/system-administration.md +32 -0
- package/skills/nocobase-app-development/references/system-settings.md +4 -4
- package/skills/nocobase-app-development/references/testing/cli/command.md +157 -0
- package/skills/nocobase-app-development/references/testing/cli/files.md +258 -0
- package/skills/nocobase-app-development/references/testing/client/page.md +301 -0
- package/skills/nocobase-app-development/references/testing/database/migration.md +50 -0
- package/skills/nocobase-app-development/references/testing/database/repository.md +160 -0
- package/skills/nocobase-app-development/references/testing/playwright/login.md +147 -0
- package/skills/nocobase-app-development/references/testing/server/routes.md +178 -0
- package/skills/nocobase-app-development/references/testing.md +53 -0
- package/skills/nocobase-app-upgrade/SKILL.md +2 -0
- package/skills/nocobase-app-upgrade/references/edge-cases.md +12 -0
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Server example: authentication, permissions, validation and persistence
|
|
2
|
+
|
|
3
|
+
Use `createAppTest()` when the behavior depends on the application's registered plugins, migrations, seeds and HTTP middleware. Requests pass through the real server in process; this fixture does not open a listening HTTP port. The following complete example covers anonymous access, administrator access, user creation and permissions, invalid input and a missing record.
|
|
4
|
+
|
|
5
|
+
## Prerequisites and configuration
|
|
6
|
+
|
|
7
|
+
Use an existing NocoBase 3 application with `server/standalone.ts`, the authentication, authorization and users plugins registered, and the default authorization policy that restricts user management to administrators. The official templates provide this composition. The example explicitly configures the initial administrator seed. If the application changes that seed or its policy, adapt the test identities and expected permissions to the actual application.
|
|
8
|
+
|
|
9
|
+
The users API provides an existing route to demonstrate the fixture. For feature work, import and test the real application composition and replace these cases with the feature's routes and permission boundaries; do not retain copies of framework tests as feature coverage.
|
|
10
|
+
|
|
11
|
+
Create `vitest.server.config.ts` at the application root:
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { createNodeVitestConfig } from '@nocobase/dev-config/vitest/node';
|
|
15
|
+
|
|
16
|
+
export default createNodeVitestConfig({
|
|
17
|
+
cacheDir: './storage/tests/vite-server',
|
|
18
|
+
test: {
|
|
19
|
+
include: ['tests/server/**/*.test.ts'],
|
|
20
|
+
fileParallelism: false,
|
|
21
|
+
passWithNoTests: false,
|
|
22
|
+
},
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Create the shared fixture
|
|
27
|
+
|
|
28
|
+
Create `tests/helpers/app.ts`:
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { createAppTest } from '@nocobase/app-testing/server';
|
|
32
|
+
import { DEFAULT_ADMIN_CREDENTIALS } from '@nocobase/app-plugin-authentication/testing';
|
|
33
|
+
import { createStandaloneServer } from '../../server/standalone.js';
|
|
34
|
+
|
|
35
|
+
export const test = createAppTest({
|
|
36
|
+
createServer: createStandaloneServer,
|
|
37
|
+
connections: ['main'],
|
|
38
|
+
config: {
|
|
39
|
+
app: { publicOrigin: 'http://localhost' },
|
|
40
|
+
auth: {
|
|
41
|
+
secret: 'test-auth-secret-at-least-32-characters',
|
|
42
|
+
trustedOrigins: ['http://localhost'],
|
|
43
|
+
},
|
|
44
|
+
users: { initialAdmin: DEFAULT_ADMIN_CREDENTIALS },
|
|
45
|
+
},
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
This provisions `main`. Name every application-owned connection in `connections`, for example `['main', 'analytics']` for an application owning both. An omitted connection keeps the application's configuration; it is not automatically replaced with a test database. Do not override the provisioned connection's host, database or storage in `config.database.connections`.
|
|
50
|
+
|
|
51
|
+
The application must honor the supplied `configPath`, as the templates do. Migrations and seeds run by default; use `install: false` only when the test installs them itself. The auth values above are fixed test-only values, and the storage directory is temporary.
|
|
52
|
+
|
|
53
|
+
## Exercise the route
|
|
54
|
+
|
|
55
|
+
Create `tests/server/users.test.ts`:
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
import {
|
|
59
|
+
DEFAULT_ADMIN_CREDENTIALS,
|
|
60
|
+
signIn,
|
|
61
|
+
} from '@nocobase/app-plugin-authentication/testing';
|
|
62
|
+
import { expect } from 'vitest';
|
|
63
|
+
import { test } from '../helpers/app.js';
|
|
64
|
+
|
|
65
|
+
test('returns 401 without a session', async ({ request }) => {
|
|
66
|
+
const response = await request('/users');
|
|
67
|
+
|
|
68
|
+
expect(response.status).toBe(401);
|
|
69
|
+
await expect(response.json()).resolves.toMatchObject({
|
|
70
|
+
error: { status: 'UNAUTHENTICATED' },
|
|
71
|
+
});
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
test('returns the administrator record after sign-in', async ({ testApp }) => {
|
|
75
|
+
const admin = await signIn(testApp, DEFAULT_ADMIN_CREDENTIALS);
|
|
76
|
+
const response = await admin.fetch(
|
|
77
|
+
`/users?q=${encodeURIComponent(admin.user.email)}`,
|
|
78
|
+
);
|
|
79
|
+
|
|
80
|
+
expect(response.status).toBe(200);
|
|
81
|
+
await expect(response.json()).resolves.toMatchObject({
|
|
82
|
+
data: expect.arrayContaining([
|
|
83
|
+
expect.objectContaining({
|
|
84
|
+
id: admin.user.id,
|
|
85
|
+
email: DEFAULT_ADMIN_CREDENTIALS.email,
|
|
86
|
+
}),
|
|
87
|
+
]),
|
|
88
|
+
});
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
test('creates a user but denies that user access to the users list', async ({
|
|
92
|
+
testApp,
|
|
93
|
+
}) => {
|
|
94
|
+
const admin = await signIn(testApp, DEFAULT_ADMIN_CREDENTIALS);
|
|
95
|
+
const credentials = {
|
|
96
|
+
email: 'server-test-member@example.com',
|
|
97
|
+
password: 'test-member-password',
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
const created = await admin.fetch('/users', {
|
|
101
|
+
method: 'POST',
|
|
102
|
+
headers: {
|
|
103
|
+
'content-type': 'application/json',
|
|
104
|
+
origin: 'http://localhost',
|
|
105
|
+
},
|
|
106
|
+
body: JSON.stringify({ name: 'Test member', ...credentials }),
|
|
107
|
+
});
|
|
108
|
+
expect(created.status).toBe(201);
|
|
109
|
+
|
|
110
|
+
const member = await signIn(testApp, credentials);
|
|
111
|
+
const forbidden = await member.fetch('/users');
|
|
112
|
+
expect(forbidden.status).toBe(403);
|
|
113
|
+
await expect(forbidden.json()).resolves.toMatchObject({
|
|
114
|
+
error: { status: 'PERMISSION_DENIED' },
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
const saved = await admin.fetch(
|
|
118
|
+
`/users?q=${encodeURIComponent(credentials.email)}`,
|
|
119
|
+
);
|
|
120
|
+
expect(saved.status).toBe(200);
|
|
121
|
+
await expect(saved.json()).resolves.toMatchObject({
|
|
122
|
+
data: expect.arrayContaining([
|
|
123
|
+
expect.objectContaining({
|
|
124
|
+
id: member.user.id,
|
|
125
|
+
name: 'Test member',
|
|
126
|
+
email: credentials.email,
|
|
127
|
+
}),
|
|
128
|
+
]),
|
|
129
|
+
});
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
test('returns 400 for an invalid page number', async ({ testApp }) => {
|
|
133
|
+
const admin = await signIn(testApp, DEFAULT_ADMIN_CREDENTIALS);
|
|
134
|
+
const response = await admin.fetch('/users?page=0');
|
|
135
|
+
|
|
136
|
+
expect(response.status).toBe(400);
|
|
137
|
+
await expect(response.json()).resolves.toMatchObject({
|
|
138
|
+
error: { status: 'INVALID_ARGUMENT' },
|
|
139
|
+
});
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
test('returns 404 for a missing user', async ({ testApp }) => {
|
|
143
|
+
const admin = await signIn(testApp, DEFAULT_ADMIN_CREDENTIALS);
|
|
144
|
+
const response = await admin.fetch('/users/server-test-missing-user', {
|
|
145
|
+
method: 'PATCH',
|
|
146
|
+
headers: {
|
|
147
|
+
'content-type': 'application/json',
|
|
148
|
+
origin: 'http://localhost',
|
|
149
|
+
},
|
|
150
|
+
body: JSON.stringify({ name: 'Updated name' }),
|
|
151
|
+
});
|
|
152
|
+
|
|
153
|
+
expect(response.status).toBe(404);
|
|
154
|
+
await expect(response.json()).resolves.toMatchObject({
|
|
155
|
+
error: { status: 'NOT_FOUND', reason: 'USER_NOT_FOUND' },
|
|
156
|
+
});
|
|
157
|
+
});
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`request('/users')` is anonymous and resolves below the application's API root, including its deployment base path. `signIn()` performs a real sign-in; `admin.fetch()` and `member.fetch()` attach the resulting session cookie. Pass `/users`, not `/api/users` or `/main/api/users`. Mutating requests in this example also send the trusted `origin` and JSON content type.
|
|
161
|
+
|
|
162
|
+
The response checks distinguish `401 UNAUTHENTICATED`, `403 PERMISSION_DENIED`, `400 INVALID_ARGUMENT` and `404 NOT_FOUND` with `USER_NOT_FOUND`. The creation case verifies persistence by reading the created user back through the administrator's API; it then verifies that the new user's session cannot list users.
|
|
163
|
+
|
|
164
|
+
## Isolation and cleanup
|
|
165
|
+
|
|
166
|
+
`createAppTest()` defaults to `scope: 'file'`: cases share one application and its database. The example's only writing case creates its own user and does not depend on another case's data; the remaining cases read the administrator or reject invalid requests. Do not make later tests depend on the created user. Use unique identities for additional writing cases, clean up their records when needed, or choose `scope: 'test'` in the fixture options when each case needs a freshly installed application.
|
|
167
|
+
|
|
168
|
+
The fixture closes the application before dropping its databases and deleting temporary storage. When using `createTestApp()` directly, close it in `finally` with `await testApp.close()`. When using `createAppTest()`, let the fixture own cleanup; closing it inside a case would invalidate the other cases in the same file. Run server and database suites sequentially.
|
|
169
|
+
|
|
170
|
+
## Run and check
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
pnpm exec vitest run --config vitest.server.config.ts --reporter=verbose
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Expect five passing cases covering `401`, `200`, `201` followed by `403`, `400`, and `404`. An ordinary user's `403` must come from the real permission middleware, not an always-allow or always-deny mock.
|
|
177
|
+
|
|
178
|
+
For application-owned routes, also verify the route's [API declaration](../../testing.md#the-api-document). Return to [testing and verification](../../testing.md).
|
|
@@ -1,5 +1,58 @@
|
|
|
1
1
|
# Testing and verification
|
|
2
2
|
|
|
3
|
+
## Testing with `@nocobase/app-testing`
|
|
4
|
+
|
|
5
|
+
Application tests use `@nocobase/app-testing` in `devDependencies`. It exposes `/server`, `/client` and `/cli`; choose the entry that matches the test environment. Use the real repository, application composition or command class whose behavior the test needs to prove. The examples below are references of the `nocobase-app-development` Skill delivered by `@nocobase/app-skills`.
|
|
6
|
+
|
|
7
|
+
### Worked examples by directory
|
|
8
|
+
|
|
9
|
+
Start with the example for the boundary you need to test. These examples run from a NocoBase 3 application's root and use its installed packages; they do not require the NocoBase source repository.
|
|
10
|
+
|
|
11
|
+
| Directory | Example | Runtime and entry |
|
|
12
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
13
|
+
| `database/` | [Records, constraints, transactions and isolation](testing/database/repository.md), [apply, roll back and reapply a migration](testing/database/migration.md) | Node; `@nocobase/app-testing/server` |
|
|
14
|
+
| `server/` | [Authentication, permissions, validation and persistence](testing/server/routes.md) | Node; `@nocobase/app-testing/server` |
|
|
15
|
+
| `client/` | [Submit from a component with the real API client and translations](testing/client/page.md) | jsdom; `@nocobase/app-testing/client` |
|
|
16
|
+
| `cli/` | [Test file output, dry runs and failures](testing/cli/files.md), [run a database-backed command](testing/cli/command.md) | Node; `@nocobase/app-testing/cli` |
|
|
17
|
+
| `playwright/` | [Sign in once and reuse the browser session](testing/playwright/login.md) | Browser; `@playwright/test` against a running application |
|
|
18
|
+
|
|
19
|
+
The directory names organize the examples and their suggested test files. They are not five package exports: database fixtures come from `/server`, and there is no `@nocobase/app-testing/database` or `@nocobase/app-testing/playwright` entry. Playwright tests use an actual application URL; the server fixture handles requests in process without opening a browser-accessible port.
|
|
20
|
+
|
|
21
|
+
The examples assume `@nocobase/app-testing`, Vitest and the selected database driver are installed at versions compatible with the application. The client example additionally uses the React Vitest preset, Testing Library and jsdom already configured by the official templates. Each example lists its additional prerequisites. Run the named file and confirm it appears in the test summary; a successful command with no tests found is not verification.
|
|
22
|
+
|
|
23
|
+
The examples use `tests/database/`, `tests/server/`, `tests/client/`, `tests/cli/` and `tests/playwright/`. An existing application may still use the `logic/` and `components/` layout below; follow its current conventions instead of moving unrelated tests. Directory names alone do not select a Vitest environment. Each complete Vitest example supplies a dedicated configuration that selects Node or jsdom and limits test discovery; use the matching `--config` when running it. When adopting the files into the regular suite, use the application's existing environment selection or Vitest projects and keep `tests/playwright/**` excluded from Vitest. Preserve existing aliases, setup files and test discovery.
|
|
24
|
+
|
|
25
|
+
### Fixture selection and ownership
|
|
26
|
+
|
|
27
|
+
| What the test exercises | Helper | Isolation and cleanup |
|
|
28
|
+
| --------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| Repositories and transactions without application startup | `createDatabaseTest()` from `/server` | `isolation: 'schema'` resets and migrates before each case; the fixture destroys connections and drops its databases |
|
|
30
|
+
| A migration's schema and rollback | `describeMigration()` from `/server` | Owns its database and checks apply → rollback → reapply; `up` assertions run twice |
|
|
31
|
+
| Routes, providers, plugins and authentication | `createAppTest()` from `/server` | Default `scope: 'file'` shares an application; `scope: 'test'` installs a fresh one per case; cleanup is automatic |
|
|
32
|
+
| A manually started test application | `createTestApp()` from `/server` | The caller closes it in `finally` with `await testApp.close()` |
|
|
33
|
+
| Components using application services | `renderWithApp()` from `/client` | Call inside a test; client shutdown is automatic and the React preset cleans up the DOM |
|
|
34
|
+
| A command operating on files or flags | `bindAppCommand()` + `runAppCommand()` from `/cli` | The test owns its temporary files; command output capture is process-wide |
|
|
35
|
+
| A command opening the real application | `createTestAppConfig()` + `bindTestAppCommand()` from `/cli` | The caller disposes the configuration in `finally`; `withApp()` closes the command's application |
|
|
36
|
+
|
|
37
|
+
For database, server and database-backed CLI tests, `NOCOBASE_TEST_DB_DIALECT` selects the dialect; unset means SQLite. Provision every application-owned connection by listing it in `connections`. An omitted connection keeps the application's configuration. Keep provisioned connection locations intact; use test configuration overrides for auth, seeds or other settings. Pure repository tests take explicit migration and seed sources; application fixtures install the application's registered sources by default.
|
|
38
|
+
|
|
39
|
+
Run database and server suites sequentially. CLI stream capture and environment stubs are process-wide, so do not use concurrent command cases. Keep temporary storage under the fixture's ownership, and never clean up a shared development database or a running Vite cache.
|
|
40
|
+
|
|
41
|
+
### Run a complete example
|
|
42
|
+
|
|
43
|
+
After creating the files in the linked examples, run from the application root:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pnpm exec vitest run --config vitest.database.config.ts
|
|
47
|
+
pnpm exec vitest run --config vitest.server.config.ts
|
|
48
|
+
pnpm exec vitest run --config vitest.client.config.ts
|
|
49
|
+
pnpm exec vitest run --config vitest.cli.config.ts
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Run these commands one at a time. With all four groups copied, expect five database tests (including the migration), five server tests, five client tests and eight CLI tests (six file-command cases and two database-backed cases). A copied subset has the corresponding smaller count. The sample configurations set `passWithNoTests: false`; when using an existing configuration, still confirm that the named files ran.
|
|
53
|
+
|
|
54
|
+
If startup fails, check the installed package exports, the selected driver, the fixture's migration sources and the application's registered plugins before replacing a real service with a mock. A missing collection in a repository test usually needs its migration sources; failed sign-in needs the configured test seed and trusted origin; a server `403` with a valid session needs the intended grants. Client translation failures need the real namespace and locale keys, and CLI JSON failures need assertions on `exitCode` and the JSON error envelope.
|
|
55
|
+
|
|
3
56
|
## Where tests go
|
|
4
57
|
|
|
5
58
|
```text
|
|
@@ -164,3 +164,5 @@ Report the range merged, how each contested file was decided, any manual actions
|
|
|
164
164
|
## Crossing several releases
|
|
165
165
|
|
|
166
166
|
Compare BASE directly with TARGET and merge the resulting changes once. Check the user's code against changed or removed contracts and preserve existing configuration, data, and migration history. If a compatibility step cannot be determined from the endpoints, inspect the relevant intermediate release or ask for the missing project context; do not assume every historical instruction applies.
|
|
167
|
+
|
|
168
|
+
When the target adds or changes the standard process UI sources, also follow [standard process management source upgrades](references/edge-cases.md#standard-process-management-source-upgrades): confirm existing process pages actually consume the merged components, while preserving explicit user customizations, parameters, grants and history.
|
|
@@ -233,3 +233,15 @@ NocoBase Hub is discontinued, and with it `@nocobase/hub-cli` and the `pnpm noco
|
|
|
233
233
|
## Permission editor source upgrades
|
|
234
234
|
|
|
235
235
|
When the target template changes the permission workspace, reconcile `client/components/permission-editor.tsx`, its `permission-filter.tsx` input and declared UI primitives (including `checkbox` and `popover`), `client/pages/settings/permissions-model.ts`, the role form callback bindings, `permission-filters.tsx` and localized labels together. Resource rows use action checkboxes with scopes attached to their owning action; scope controls are not additional permissions. The optional `onEnabledBatchChange` reports one atomic batch for visible toggleable actions; bind it with one functional draft update that retains unknown grants, policies and scopes. Existing consumers without that callback retain individual action editing. Preserve application-specific resource registration, protected roles, save/revision checks and server authorization. Include a multi-action selection test and a test retaining existing scope policies. Registry source copies do not update themselves when the registry site publishes; bring this interaction in through the template source merge, preserving application customizations.
|
|
236
|
+
|
|
237
|
+
## Standard process management source upgrades
|
|
238
|
+
|
|
239
|
+
When TARGET introduces the preinstalled `flow-diagram`, `lifecycle-diagram` and workflow-management sources, merge those files, their React Flow/ELK client dependencies, standard DataTable and locale keys together. Add no workflow routes, menus or sample business data to an application that has no process. For applications with processes, inspect their actual management renderer and editor after the source merge; adding unused files alone does not upgrade a rendered page.
|
|
240
|
+
|
|
241
|
+
Follow the target's [default process UI contract](../../nocobase-app-development/references/lifecycle-ui.md#default-diagram-and-configuration-contract). Reuse existing route ids, catalog aggregation, stored parameters/revisions, role grants and execution history. Adapt a legacy technical Mermaid fallback to the standard component when it was not an explicit user style choice, and connect declared authorized bindings to the same real parameter editor through `LifecycleDiagram.configuration`. Preserve intentional user visual customizations and application-owned behavior; do not overwrite a custom page wholesale. An npm 404 recorded in old maintenance notes is not evidence that a UI Registry item was unavailable. Remove such stale technical fallback explanations after verified migration.
|
|
242
|
+
|
|
243
|
+
Verify the rendered directory/detail/history pages and parameter read/save behavior, including denied writes and snapshots, rather than considering the upgrade complete merely because graph source files exist. Report any required renderer/editor adaptation that remains unverified. A template upgrade carries source through reconciliation; a registry website release or dependency version bump alone never replaces an application's copied components.
|
|
244
|
+
|
|
245
|
+
## Page permission label upgrades
|
|
246
|
+
|
|
247
|
+
Reconcile `client/pages/settings/page-permissions.ts`, the role form's catalog adapter, the application-owned `page-permission-titles.ts` mapping, the localized unnamed-page fallback and `tests/logic/page-permission-titles.test.ts` together. Preserve existing mapping entries, route names, resource ids, actions, grants and policies; add translations for untitled page permissions rather than changing their authorization or adding breadcrumbs to overlays. Check the application's actual resolved routes in both languages, not just the bare template.
|