Skip to content

Commit

Permalink
feat: expose stringifyStep (#163)
Browse files Browse the repository at this point in the history
This is needed to allow for partial step by step stringification.

BREAKING CHANGE: flow parameter is now optional in before/after/step hooks.
  • Loading branch information
OrKoN committed Jun 1, 2022
1 parent a450575 commit 50f595d
Show file tree
Hide file tree
Showing 8 changed files with 177 additions and 16 deletions.
7 changes: 7 additions & 0 deletions __snapshots__/stringifyStep_test.ts.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
exports['stringifyStep should stringify a single step 1'] = `
{
const targetPage = page;
await targetPage.goto("https://localhost/");
}
`;
36 changes: 35 additions & 1 deletion docs/api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
- [parse](README.md#parse)
- [parseStep](README.md#parsestep)
- [stringify](README.md#stringify)
- [stringifyStep](README.md#stringifystep)

## Functions

Expand Down Expand Up @@ -96,6 +97,13 @@ ___

**stringify**(`flow`, `opts?`): `Promise`<`string`\>

Stringifes an entire recording. The following hooks are invoked with the `flow` parameter containing the entire flow:
- `beforeAllSteps` (once)
- `beforeEachStep` (per step)
- `stringifyStep` (per step)
- `afterEachStep` (per step)
- `afterAllSteps` (once)

#### Parameters

| Name | Type |
Expand All @@ -109,4 +117,30 @@ ___

#### Defined in

[stringify.ts:27](https://github.com/puppeteer/replay/blob/main/src/stringify.ts#L27)
[stringify.ts:35](https://github.com/puppeteer/replay/blob/main/src/stringify.ts#L35)

___

### stringifyStep

**stringifyStep**(`step`, `opts?`): `Promise`<`string`\>

Stringifes a single step. Only the following hooks are invoked with the `flow` parameter as undefined:
- `beforeEachStep`
- `stringifyStep`
- `afterEachStep`

#### Parameters

| Name | Type |
| :------ | :------ |
| `step` | [`Step`](modules/Schema.md#step) |
| `opts?` | [`StringifyOptions`](interfaces/StringifyOptions.md) |

#### Returns

`Promise`<`string`\>

#### Defined in

[stringify.ts:69](https://github.com/puppeteer/replay/blob/main/src/stringify.ts#L69)
8 changes: 4 additions & 4 deletions docs/api/classes/PuppeteerStringifyExtension.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,15 +61,15 @@ ___

### afterEachStep

`Optional` **afterEachStep**(`out`, `step`, `flow`): `Promise`<`void`\>
`Optional` **afterEachStep**(`out`, `step`, `flow?`): `Promise`<`void`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `out` | [`LineWriter`](../interfaces/LineWriter.md) |
| `step` | [`Step`](../modules/Schema.md#step) |
| `flow` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |
| `flow?` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |

#### Returns

Expand Down Expand Up @@ -112,15 +112,15 @@ ___

### beforeEachStep

`Optional` **beforeEachStep**(`out`, `step`, `flow`): `Promise`<`void`\>
`Optional` **beforeEachStep**(`out`, `step`, `flow?`): `Promise`<`void`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `out` | [`LineWriter`](../interfaces/LineWriter.md) |
| `step` | [`Step`](../modules/Schema.md#step) |
| `flow` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |
| `flow?` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |

#### Returns

Expand Down
12 changes: 6 additions & 6 deletions docs/api/classes/StringifyExtension.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,15 +53,15 @@ ___

### afterEachStep

`Optional` **afterEachStep**(`out`, `step`, `flow`): `Promise`<`void`\>
`Optional` **afterEachStep**(`out`, `step`, `flow?`): `Promise`<`void`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `out` | [`LineWriter`](../interfaces/LineWriter.md) |
| `step` | [`Step`](../modules/Schema.md#step) |
| `flow` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |
| `flow?` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |

#### Returns

Expand Down Expand Up @@ -96,15 +96,15 @@ ___

### beforeEachStep

`Optional` **beforeEachStep**(`out`, `step`, `flow`): `Promise`<`void`\>
`Optional` **beforeEachStep**(`out`, `step`, `flow?`): `Promise`<`void`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `out` | [`LineWriter`](../interfaces/LineWriter.md) |
| `step` | [`Step`](../modules/Schema.md#step) |
| `flow` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |
| `flow?` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |

#### Returns

Expand All @@ -118,15 +118,15 @@ ___

### stringifyStep

**stringifyStep**(`out`, `step`, `flow`): `Promise`<`void`\>
**stringifyStep**(`out`, `step`, `flow?`): `Promise`<`void`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `out` | [`LineWriter`](../interfaces/LineWriter.md) |
| `step` | [`Step`](../modules/Schema.md#step) |
| `flow` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |
| `flow?` | [`UserFlow`](../interfaces/Schema.UserFlow.md) |

#### Returns

Expand Down
6 changes: 3 additions & 3 deletions src/StringifyExtension.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,16 @@ export class StringifyExtension {
async beforeEachStep?(
out: LineWriter,
step: Step,
flow: UserFlow
flow?: UserFlow
): Promise<void> {}
async stringifyStep(
out: LineWriter,
step: Step,
flow: UserFlow
flow?: UserFlow
): Promise<void> {}
async afterEachStep?(
out: LineWriter,
step: Step,
flow: UserFlow
flow?: UserFlow
): Promise<void> {}
}
2 changes: 1 addition & 1 deletion src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
export * as Schema from './Schema.js';
export { parse, parseStep } from './SchemaUtils.js';
export { StringifyExtension } from './StringifyExtension.js';
export { stringify, StringifyOptions } from './stringify.js';
export { stringify, stringifyStep, StringifyOptions } from './stringify.js';
export { LineWriter } from './LineWriter.js';
export { RunnerExtension } from './RunnerExtension.js';
export { createRunner, Runner } from './Runner.js';
Expand Down
39 changes: 38 additions & 1 deletion src/stringify.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,22 @@

import { LineWriterImpl } from './LineWriterImpl.js';
import { PuppeteerStringifyExtension } from './PuppeteerStringifyExtension.js';
import type { UserFlow } from './Schema.js';
import type { Step, UserFlow } from './Schema.js';
import { StringifyExtension } from './StringifyExtension.js';

export interface StringifyOptions {
extension?: StringifyExtension;
indentation?: string;
}

/**
* Stringifes an entire recording. The following hooks are invoked with the `flow` parameter containing the entire flow:
* - `beforeAllSteps` (once)
* - `beforeEachStep` (per step)
* - `stringifyStep` (per step)
* - `afterEachStep` (per step)
* - `afterAllSteps` (once)
*/
export async function stringify(
flow: UserFlow,
opts?: StringifyOptions
Expand Down Expand Up @@ -51,3 +59,32 @@ export async function stringify(

return out.toString();
}

/**
* Stringifes a single step. Only the following hooks are invoked with the `flow` parameter as undefined:
* - `beforeEachStep`
* - `stringifyStep`
* - `afterEachStep`
*/
export async function stringifyStep(
step: Step,
opts?: StringifyOptions
): Promise<string> {
if (!opts) {
opts = {};
}
let ext = opts.extension;
if (!ext) {
ext = new PuppeteerStringifyExtension();
}
if (!opts.indentation) {
opts.indentation = ' ';
}
const out = new LineWriterImpl(opts.indentation);

await ext.beforeEachStep?.(out, step);
await ext.stringifyStep(out, step);
await ext.afterEachStep?.(out, step);

return out.toString();
}
83 changes: 83 additions & 0 deletions test/stringifyStep_test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
/**
Copyright 2022 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

import { stringifyStep } from '../src/stringify.js';
import { assert } from 'chai';
import { StringifyExtension } from '../src/StringifyExtension.js';
import { Step, UserFlow } from '../src/Schema.js';
import { LineWriter } from '../src/LineWriter.js';
import snapshot from 'snap-shot-it';

describe('stringifyStep', () => {
it('should stringify a single step', async () => {
snapshot(
await stringifyStep({
type: 'navigate' as const,
url: 'https://localhost/',
})
);
});

it('invokes all hooks in extensions relevant for stringifyStep', async () => {
class DummyExtension implements StringifyExtension {
async beforeAllSteps(out: LineWriter): Promise<void> {
out.appendLine('beforeAll');
}

async beforeEachStep(
out: LineWriter,
step: Step,
flow?: UserFlow
): Promise<void> {
out.appendLine('beforeStep ' + flow);
}

async stringifyStep(
out: LineWriter,
step: Step,
flow?: UserFlow
): Promise<void> {
out.appendLine('stringifyStep ' + flow);
}

async afterEachStep(
out: LineWriter,
step: Step,
flow?: UserFlow
): Promise<void> {
out.appendLine('afterStep ' + flow);
}

async afterAllSteps(out: LineWriter): Promise<void> {
out.appendLine('afterAll');
}
}

const extension = new DummyExtension();
assert.strictEqual(
await stringifyStep(
{ type: 'customStep', name: 'test', parameters: {} },
{ extension }
),
[
'beforeStep undefined',
'stringifyStep undefined',
'afterStep undefined',
'',
].join('\n')
);
});
});

0 comments on commit 50f595d

Please sign in to comment.