serenity-process 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +72 -2
- package/lib/Process.d.ts +44 -0
- package/lib/Process.js +75 -0
- package/lib/Step.d.ts +29 -0
- package/lib/Step.js +17 -0
- package/lib/Subprocess.d.ts +27 -0
- package/lib/Subprocess.js +29 -0
- package/lib/index.d.ts +5 -0
- package/lib/index.js +9 -0
- package/package.json +24 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Timber Kerkvliet
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,73 @@
|
|
|
1
|
-
#
|
|
1
|
+
# serenity-process
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A **Process** is like a [Serenity/JS](https://serenity-js.org) `Task`, but performed by
|
|
4
|
+
**several actors**, each playing a role.
|
|
5
|
+
|
|
6
|
+
```ts
|
|
7
|
+
import { Process, step } from 'serenity-process';
|
|
8
|
+
|
|
9
|
+
const escalation = Process.where('#customer raises an urgent ticket that #agent resolves',
|
|
10
|
+
step('customer', raiseTicket({ priority: 'urgent' })),
|
|
11
|
+
step('agent', resolveTicket()),
|
|
12
|
+
);
|
|
13
|
+
|
|
14
|
+
await When(escalation.with({ customer: chidi, agent: priya }));
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Report output reads: `Chidi, as customer, in: Chidi raises an urgent ticket that Priya resolves`.
|
|
18
|
+
|
|
19
|
+
## Behaviour
|
|
20
|
+
|
|
21
|
+
- Steps run **in order**, one after another; the process **stops at the first failing step**.
|
|
22
|
+
- A role may appear in **more than one step**.
|
|
23
|
+
- Actors are bound only when running (`.with(...)`), so a process can be **reused** with other actors.
|
|
24
|
+
- `.with()` throws a `LogicError` if a role has no actor (and TypeScript checks the role names).
|
|
25
|
+
- `#role` in the description is replaced by the playing actor's name.
|
|
26
|
+
- `.with()` returns `() => Promise<void>`, so it can be passed straight to `Given`, `When` or `Then`.
|
|
27
|
+
- `process.roles()` lists the roles in order of first appearance.
|
|
28
|
+
|
|
29
|
+
## Nested processes
|
|
30
|
+
|
|
31
|
+
A step can itself be a process. `subprocess(child, mapping)` binds the child's roles to roles of the
|
|
32
|
+
enclosing process:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { Process, step, subprocess } from 'serenity-process';
|
|
36
|
+
|
|
37
|
+
const purchase = Process.where('#buyer pays #seller',
|
|
38
|
+
step('buyer', pay()),
|
|
39
|
+
step('seller', ship()),
|
|
40
|
+
);
|
|
41
|
+
|
|
42
|
+
const checkout = Process.where('#customer checks out, #agent follows up',
|
|
43
|
+
step('customer', browse()),
|
|
44
|
+
subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
|
|
45
|
+
step('agent', sendInvoice()),
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
await When(checkout.with({ customer: chidi, agent: priya }));
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- Child roles not listed in the mapping keep their name; with no mapping at all the roles pass straight through.
|
|
52
|
+
- Several child roles may map to the same parent role (one actor plays both).
|
|
53
|
+
- The parent's roles (and what `.with()` requires) are inferred by TypeScript, nested ones included.
|
|
54
|
+
- Nesting can go as deep as you like; the first failing step stops everything.
|
|
55
|
+
- Report descriptions show the path: `Priya, as seller, in: Chidi checks out, Priya follows up > Chidi pays Priya`.
|
|
56
|
+
|
|
57
|
+
## Install
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm install serenity-process
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Requires `@serenity-js/core` ^3 as a peer dependency.
|
|
64
|
+
|
|
65
|
+
## Development
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npm install
|
|
69
|
+
npm test
|
|
70
|
+
npm run build
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
MIT licensed.
|
package/lib/Process.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { RoleBindings, RolesOf, Step } from './Step';
|
|
2
|
+
/**
|
|
3
|
+
* Like a `Task`, but performed by several actors, each playing a role.
|
|
4
|
+
*
|
|
5
|
+
* The steps run in the order given, one after another, and the process stops at
|
|
6
|
+
* the first step that fails. A role may appear in more than one step. The actors
|
|
7
|
+
* are only chosen when the process is run, with {@link Process.with}, so the same
|
|
8
|
+
* process can be reused with other actors.
|
|
9
|
+
*
|
|
10
|
+
* In the description, `#role` is replaced by the name of the actor playing it.
|
|
11
|
+
* A step may itself be a process, see {@link subprocess}.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* const escalation = Process.where('#customer raises an urgent ticket that #agent resolves',
|
|
15
|
+
* step('customer', raiseTicket({ priority: 'urgent' })),
|
|
16
|
+
* step('agent', resolveTicket()),
|
|
17
|
+
* );
|
|
18
|
+
*
|
|
19
|
+
* await When(escalation.with({ customer: chidi, agent: priya }));
|
|
20
|
+
*/
|
|
21
|
+
export declare class Process<Role extends string> {
|
|
22
|
+
private readonly description;
|
|
23
|
+
private readonly steps;
|
|
24
|
+
static where<Steps extends [Step<string>, ...Step<string>[]]>(description: string, ...steps: Steps): Process<RolesOf<Steps[number]>>;
|
|
25
|
+
private constructor();
|
|
26
|
+
/** The roles in this process, in order of first appearance. */
|
|
27
|
+
roles(): Role[];
|
|
28
|
+
/**
|
|
29
|
+
* Binds an actor to every role. Returns a function that runs the process,
|
|
30
|
+
* so it can be passed straight to `Given`, `When` or `Then`.
|
|
31
|
+
*/
|
|
32
|
+
with(bindings: RoleBindings<Role>): () => Promise<void>;
|
|
33
|
+
/**
|
|
34
|
+
* Runs the steps in order with the given actors. `context` is the description
|
|
35
|
+
* of the enclosing process when this one is nested, and is used by
|
|
36
|
+
* {@link subprocess} - call {@link Process.with} instead.
|
|
37
|
+
*
|
|
38
|
+
* @internal
|
|
39
|
+
*/
|
|
40
|
+
run(bindings: RoleBindings<Role>, context?: string): Promise<void>;
|
|
41
|
+
/** The description with every `#role` replaced by the name of its actor. */
|
|
42
|
+
describedFor(bindings: RoleBindings<Role>): string;
|
|
43
|
+
toString(): string;
|
|
44
|
+
}
|
package/lib/Process.js
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Process = void 0;
|
|
4
|
+
const core_1 = require("@serenity-js/core");
|
|
5
|
+
/**
|
|
6
|
+
* Like a `Task`, but performed by several actors, each playing a role.
|
|
7
|
+
*
|
|
8
|
+
* The steps run in the order given, one after another, and the process stops at
|
|
9
|
+
* the first step that fails. A role may appear in more than one step. The actors
|
|
10
|
+
* are only chosen when the process is run, with {@link Process.with}, so the same
|
|
11
|
+
* process can be reused with other actors.
|
|
12
|
+
*
|
|
13
|
+
* In the description, `#role` is replaced by the name of the actor playing it.
|
|
14
|
+
* A step may itself be a process, see {@link subprocess}.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* const escalation = Process.where('#customer raises an urgent ticket that #agent resolves',
|
|
18
|
+
* step('customer', raiseTicket({ priority: 'urgent' })),
|
|
19
|
+
* step('agent', resolveTicket()),
|
|
20
|
+
* );
|
|
21
|
+
*
|
|
22
|
+
* await When(escalation.with({ customer: chidi, agent: priya }));
|
|
23
|
+
*/
|
|
24
|
+
class Process {
|
|
25
|
+
static where(description, ...steps) {
|
|
26
|
+
return new Process(description, steps);
|
|
27
|
+
}
|
|
28
|
+
constructor(description, steps) {
|
|
29
|
+
this.description = description;
|
|
30
|
+
this.steps = steps;
|
|
31
|
+
}
|
|
32
|
+
/** The roles in this process, in order of first appearance. */
|
|
33
|
+
roles() {
|
|
34
|
+
return [...new Set(this.steps.flatMap(s => s.roles))];
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Binds an actor to every role. Returns a function that runs the process,
|
|
38
|
+
* so it can be passed straight to `Given`, `When` or `Then`.
|
|
39
|
+
*/
|
|
40
|
+
with(bindings) {
|
|
41
|
+
const missing = this.roles().filter(name => !bindings[name]);
|
|
42
|
+
if (missing.length > 0) {
|
|
43
|
+
throw new core_1.LogicError(`Nobody plays ${missing.join(', ')} in "${this.description}"`);
|
|
44
|
+
}
|
|
45
|
+
return () => this.run(bindings);
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Runs the steps in order with the given actors. `context` is the description
|
|
49
|
+
* of the enclosing process when this one is nested, and is used by
|
|
50
|
+
* {@link subprocess} - call {@link Process.with} instead.
|
|
51
|
+
*
|
|
52
|
+
* @internal
|
|
53
|
+
*/
|
|
54
|
+
async run(bindings, context) {
|
|
55
|
+
const own = this.describedFor(bindings);
|
|
56
|
+
const description = context ? `${context} > ${own}` : own;
|
|
57
|
+
for (const s of this.steps) {
|
|
58
|
+
await s.perform(bindings, description);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
/** The description with every `#role` replaced by the name of its actor. */
|
|
62
|
+
describedFor(bindings) {
|
|
63
|
+
return this.roles()
|
|
64
|
+
// longest first, so #agent doesn't eat the start of #agentLead
|
|
65
|
+
.sort((a, b) => b.length - a.length)
|
|
66
|
+
.reduce((text, name) => text.replace(new RegExp(`#${escapeRegExp(name)}(?![\\w])`, 'g'), () => bindings[name].name), this.description);
|
|
67
|
+
}
|
|
68
|
+
toString() {
|
|
69
|
+
return this.description;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
exports.Process = Process;
|
|
73
|
+
function escapeRegExp(text) {
|
|
74
|
+
return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
75
|
+
}
|
package/lib/Step.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { Activity, Actor } from '@serenity-js/core';
|
|
2
|
+
/** Maps every role of a process to the actor who plays it. */
|
|
3
|
+
export type RoleBindings<Role extends string> = {
|
|
4
|
+
readonly [R in Role]: Actor;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* One step of a {@link Process}. Either a {@link step} performed by a single role,
|
|
8
|
+
* or a {@link subprocess} that involves several.
|
|
9
|
+
*/
|
|
10
|
+
export interface Step<Role extends string> {
|
|
11
|
+
/** The roles involved in this step, in order of first appearance. */
|
|
12
|
+
readonly roles: readonly Role[];
|
|
13
|
+
/**
|
|
14
|
+
* Performs the step.
|
|
15
|
+
*
|
|
16
|
+
* @param bindings The actors playing each role
|
|
17
|
+
* @param context The description of the (nested) process this step belongs to
|
|
18
|
+
*/
|
|
19
|
+
perform(bindings: RoleBindings<Role>, context: string): Promise<void>;
|
|
20
|
+
}
|
|
21
|
+
/** The roles of a step type. */
|
|
22
|
+
export type RolesOf<S> = S extends Step<infer Role> ? Role : never;
|
|
23
|
+
/**
|
|
24
|
+
* A step of a {@link Process}: the role that performs it, and its activities.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* step('customer', raiseTicket())
|
|
28
|
+
*/
|
|
29
|
+
export declare const step: <Role extends string>(role: Role, ...activities: Activity[]) => Step<Role>;
|
package/lib/Step.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.step = void 0;
|
|
4
|
+
const core_1 = require("@serenity-js/core");
|
|
5
|
+
/**
|
|
6
|
+
* A step of a {@link Process}: the role that performs it, and its activities.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* step('customer', raiseTicket())
|
|
10
|
+
*/
|
|
11
|
+
const step = (role, ...activities) => ({
|
|
12
|
+
roles: [role],
|
|
13
|
+
async perform(bindings, context) {
|
|
14
|
+
await bindings[role].attemptsTo(core_1.Task.where(`#actor, as ${role}, in: ${context}`, ...activities));
|
|
15
|
+
},
|
|
16
|
+
});
|
|
17
|
+
exports.step = step;
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { Process } from './Process';
|
|
2
|
+
import { Step } from './Step';
|
|
3
|
+
/** Maps (some of) the roles of a nested process to roles of the enclosing process. */
|
|
4
|
+
export type RoleMapping<ChildRole extends string> = {
|
|
5
|
+
readonly [R in ChildRole]?: string;
|
|
6
|
+
};
|
|
7
|
+
/** The roles a nested process contributes to its parent: mapped ones renamed, the rest unchanged. */
|
|
8
|
+
export type MappedRoles<ChildRole extends string, Mapping extends RoleMapping<ChildRole>> = {
|
|
9
|
+
[R in ChildRole]: R extends keyof Mapping ? Extract<Mapping[R], string> : R;
|
|
10
|
+
}[ChildRole];
|
|
11
|
+
/**
|
|
12
|
+
* A step of a {@link Process} that is itself a process.
|
|
13
|
+
*
|
|
14
|
+
* Roles of the nested process are played by the actors of the roles they are
|
|
15
|
+
* mapped to in the enclosing process. Roles not mentioned in `mapping` keep
|
|
16
|
+
* their name, so a nested process whose roles match its parent's needs no mapping.
|
|
17
|
+
* Several child roles may map to the same parent role.
|
|
18
|
+
*
|
|
19
|
+
* @example
|
|
20
|
+
* const purchase = Process.where('#buyer pays #seller', step('buyer', pay()), step('seller', ship()));
|
|
21
|
+
*
|
|
22
|
+
* const checkout = Process.where('#customer checks out and #agent follows up',
|
|
23
|
+
* subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
|
|
24
|
+
* step('agent', sendInvoice()),
|
|
25
|
+
* );
|
|
26
|
+
*/
|
|
27
|
+
export declare function subprocess<ChildRole extends string, const Mapping extends RoleMapping<ChildRole> = {}>(child: Process<ChildRole>, mapping?: Mapping): Step<MappedRoles<ChildRole, Mapping>>;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.subprocess = subprocess;
|
|
4
|
+
/**
|
|
5
|
+
* A step of a {@link Process} that is itself a process.
|
|
6
|
+
*
|
|
7
|
+
* Roles of the nested process are played by the actors of the roles they are
|
|
8
|
+
* mapped to in the enclosing process. Roles not mentioned in `mapping` keep
|
|
9
|
+
* their name, so a nested process whose roles match its parent's needs no mapping.
|
|
10
|
+
* Several child roles may map to the same parent role.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* const purchase = Process.where('#buyer pays #seller', step('buyer', pay()), step('seller', ship()));
|
|
14
|
+
*
|
|
15
|
+
* const checkout = Process.where('#customer checks out and #agent follows up',
|
|
16
|
+
* subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
|
|
17
|
+
* step('agent', sendInvoice()),
|
|
18
|
+
* );
|
|
19
|
+
*/
|
|
20
|
+
function subprocess(child, mapping) {
|
|
21
|
+
const parentRole = (role) => mapping?.[role] ?? role;
|
|
22
|
+
return {
|
|
23
|
+
roles: [...new Set(child.roles().map(parentRole))],
|
|
24
|
+
async perform(bindings, context) {
|
|
25
|
+
const childBindings = Object.fromEntries(child.roles().map(role => [role, bindings[parentRole(role)]]));
|
|
26
|
+
await child.run(childBindings, context);
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
}
|
package/lib/index.d.ts
ADDED
package/lib/index.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.subprocess = exports.step = exports.Process = void 0;
|
|
4
|
+
var Process_1 = require("./Process");
|
|
5
|
+
Object.defineProperty(exports, "Process", { enumerable: true, get: function () { return Process_1.Process; } });
|
|
6
|
+
var Step_1 = require("./Step");
|
|
7
|
+
Object.defineProperty(exports, "step", { enumerable: true, get: function () { return Step_1.step; } });
|
|
8
|
+
var Subprocess_1 = require("./Subprocess");
|
|
9
|
+
Object.defineProperty(exports, "subprocess", { enumerable: true, get: function () { return Subprocess_1.subprocess; } });
|
package/package.json
CHANGED
|
@@ -1,6 +1,26 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "serenity-process",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Process: like a Serenity/JS Task, but performed by several actors, each playing a role",
|
|
5
|
+
"keywords": ["serenity-js", "serenity", "testing", "bdd", "screenplay", "multi-actor", "process"],
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"main": "./lib/index.js",
|
|
8
|
+
"types": "./lib/index.d.ts",
|
|
9
|
+
"files": ["lib", "README.md", "LICENSE"],
|
|
10
|
+
"engines": { "node": ">=18" },
|
|
11
|
+
"scripts": {
|
|
12
|
+
"build": "tsc -p tsconfig.build.json",
|
|
13
|
+
"test": "vitest run",
|
|
14
|
+
"typecheck": "tsc --noEmit",
|
|
15
|
+
"prepublishOnly": "npm run typecheck && npm test && npm run build"
|
|
16
|
+
},
|
|
17
|
+
"peerDependencies": {
|
|
18
|
+
"@serenity-js/core": "^3.0.0"
|
|
19
|
+
},
|
|
20
|
+
"devDependencies": {
|
|
21
|
+
"@serenity-js/core": "^3.49.0",
|
|
22
|
+
"@types/node": "^22.0.0",
|
|
23
|
+
"typescript": "^5.6.0",
|
|
24
|
+
"vitest": "^2.1.0"
|
|
25
|
+
}
|
|
26
|
+
}
|