Skip to content

Commit 5fcc9f4

Browse files
committed
docs: update Builder Pattern API signatures for resource/setup methods
- Add options? parameter to .resource() method - Add name? and options? parameters to .setup() method - Add code examples showing new parameter usage
1 parent 699f7bd commit 5fcc9f4

2 files changed

Lines changed: 34 additions & 19 deletions

File tree

docs/overview.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -171,10 +171,10 @@ A scenario is a complete test case composed of:
171171

172172
```
173173
scenario(name, options?)
174-
.resource(name, factoryFn) // Register resources (factory function)
175-
.setup(fn) // Add setup/cleanup hooks
176-
.step(name, fn, options?) // Define test steps
177-
.build() // Create immutable definition
174+
.resource(name, factoryFn, options?) // Register resources (factory function)
175+
.setup(name?, fn, options?) // Add setup/cleanup hooks (name optional)
176+
.step(name?, fn, options?) // Define test steps (name optional)
177+
.build() // Create immutable definition
178178
```
179179

180180
### Expect API

docs/scenario.md

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -100,22 +100,29 @@ result of the previous step.
100100
})
101101
```
102102

103-
### `.resource(name, factory)`
103+
### `.resource(name, factory, options?)`
104104

105105
Registers a resource with lifecycle management. Resources are created before
106106
steps run and automatically disposed after the scenario completes.
107107

108-
| Parameter | Type | Description |
109-
| --------- | ------------ | ----------------------------------------------------- |
110-
| `name` | `string` | Name to access this resource via `ctx.resources.name` |
111-
| `factory` | `(ctx) => T` | Function that creates and returns the resource |
108+
| Parameter | Type | Description |
109+
| ---------- | ------------ | -------------------------------------------------------------------------------------- |
110+
| `name` | `string` | Name to access this resource via `ctx.resources.name` |
111+
| `factory` | `(ctx) => T` | Function that creates and returns the resource |
112+
| `options?` | `object` | Per-resource timeout and retry (see [Configuration](/docs/configuration#step-options)) |
112113

113114
```typescript
114115
.resource("http", () =>
115116
client.http.createHttpClient({
116117
url: "http://localhost:8080",
117118
})
118119
)
120+
121+
// With options
122+
.resource("db", () =>
123+
client.sql.postgres.createPostgresClient({ ... }),
124+
{ timeout: 10000 }
125+
)
119126
```
120127

121128
#### Resource Behavior
@@ -125,18 +132,20 @@ steps run and automatically disposed after the scenario completes.
125132
- Resources are available to subsequent steps, setups, and other resources
126133
- Disposal happens in reverse order after scenario completion
127134

128-
### `.setup(fn)`
135+
### `.setup(name?, fn, options?)`
129136

130137
Registers a setup hook that runs before steps. Can return a cleanup function
131138
that runs after all steps complete (even on failure).
132139

133-
| Parameter | Type | Description |
134-
| --------- | ------------------- | ----------------------------------------------------------------------- |
135-
| `fn` | `(ctx) => Cleanup?` | Setup function that optionally returns a cleanup function or Disposable |
140+
| Parameter | Type | Description |
141+
| ---------- | ------------------- | ----------------------------------------------------------------------------------- |
142+
| `name?` | `string` | Optional setup name (auto-generated as "Setup step 1", etc. if omitted) |
143+
| `fn` | `(ctx) => Cleanup?` | Setup function that optionally returns a cleanup function or Disposable |
144+
| `options?` | `object` | Per-setup timeout and retry (see [Configuration](/docs/configuration#step-options)) |
136145

137146
```typescript
138-
// Setup with cleanup function
139-
.setup(async (ctx) => {
147+
// Named setup with cleanup function
148+
.setup("Seed test data", async (ctx) => {
140149
const { db } = ctx.resources;
141150
await db.query("INSERT INTO test_data ...");
142151

@@ -145,6 +154,12 @@ that runs after all steps complete (even on failure).
145154
};
146155
})
147156

157+
// Unnamed setup (auto-named as "Setup step 1", etc.)
158+
.setup(async (ctx) => {
159+
const { db } = ctx.resources;
160+
await db.query("INSERT INTO test_data ...");
161+
})
162+
148163
// Setup with Disposable
149164
.setup((ctx) => {
150165
const resource = createResource();
@@ -155,10 +170,10 @@ that runs after all steps complete (even on failure).
155170
};
156171
})
157172

158-
// Setup without cleanup
159-
.setup((ctx) => {
160-
console.log("Setting up...");
161-
})
173+
// Setup with options
174+
.setup("Long setup", async (ctx) => {
175+
await prepareTestEnvironment();
176+
}, { timeout: 60000 })
162177
```
163178

164179
### `.build()`

0 commit comments

Comments
 (0)