feat: Implement YAML for playwright

CHANGELOG.md

@@ -1,3 +1,7 @@
+## Unreleased
+### Added
+- Add support for YAML for Playwright 
+
 ## 0.3.1
 ### Changed
 - Refactoring

README.md

@@ -111,7 +111,7 @@ scenarios:
           - expect(_.jsonBody.id).toBe(productId)
 ```
 
-For more details, refer to the [documentation](./docs/yamlScenario.md).  
+For more details, refer to the [documentation](./docs/yamlJestScenario.md) or [examples](create-echoed/template/jest/example/scenario).  
 
 ### Make Tests Observable
 
@@ -163,8 +163,36 @@ For more examples, refer to [documentation](./docs/howToUse.md#jest).
 
 You can write Playwright tests in TypeScript too.
 
+### YAML
+
+You can write tests using YAML, and Echoed will convert them into Playwright tests.  
+
+![Compilation flow](https://github.com/mrasu/echoed/raw/main/docs/img/scenarioYamlToPlaywright.jpg)
+
+The YAML below opens `http://localhost:8080` and validates DOM elements.
+
+```yaml
+scenarios:
+  - name: Validate Homepage
+    fixtures:
+      - page
+    steps:
+      - description: Check product list is shown
+        act:
+          raw: await page.goto("http://localhost:8080")
+        assert:
+          - expectToBeVisible: "[data-cy=home-page]"
+          - expectToHaveCount:
+              selector: "[data-cy=product-list] [data-cy=product-card]"
+              count: 10
+```
+
+For more details, refer to the [documentation](./docs/yamlPlaywrightScenario.md) or [examples](create-echoed/template/playwright/example/test/scenario). 
+
 ### Make Tests Observable
 
+You can write Playwright tests in TypeScript too.
+
 To generate an HTML report visualizing API traces, replace `test` of Playwright to Echoed's to intercept requests.
 
 ```ts
@@ -278,9 +306,8 @@ services:
 
 # Using Echoed without OpenTelemetry
 
-While Echoed's primary feature is to troubleshoot or analyze tests by visualizing OpenTelemetry data, it can also be used to write Jest tests in YAML.  
-To add Echoed into existing tests for writing tests in YAML, simply create a `.echoed.yml` file for configuration.  
-In the "Installation" document, you may see `nodeEnvironment` and `reporter` is added in `jest.config.js`. However, because these configurations are to collect OpenTelemetry data, when you don't use OpenTelemetry, there's no need to modify it.
+While Echoed's primary feature is to troubleshoot or analyze tests by visualizing OpenTelemetry data, it can also be used to write tests in YAML.  
+To add YAML tests into existing tests, simply create a `.echoed.yml` file for configuration and run `npx echoed compile`.  
 
 Alternatively, if you wish to create example tests without OpenTelemetry, you can do so using the following commands:
 ```bash
@@ -292,6 +319,16 @@ npx echoed compile
 npx jest
 ```
 
+Or for Playwright:
+```bash
+# Create example tests
+npm create echoed@latest -- --template playwright-no-otel
+
+# Compile YAML to TypeScript and run tests
+npx echoed compile
+npx playwright test
+```
+
 # Configuration
 
 Echoed can be configured at `.echoed.yml` in the root of your project.  

docs/howToUse.md

@@ -5,10 +5,20 @@ Documentation for Usage of Echoed.
 # Table of contents
 
 * [Jest](#Jest)
+  * [YAML](#YAML)
+  * [TypeScript](#TypeScript)
+  * [More Examples](#More-Examples)
+  * [Using Echoed without OpenTelemetry](#Using-Echoed-without-OpenTelemetry)
 * [Playwright](#Playwright)
+  * [YAML](#YAML-1)
+  * [TypeScript](#TypeScript-1)
+  * [More Examples](#More-Examples-1)
+  * [Using Echoed without OpenTelemetry](#Using-Echoed-without-OpenTelemetry-1)
 * [Cypress](#Cypress)
+  * [Make Tests Observable](#Make-Tests-Observable)
+  * [YAML](#YAML-2)
+  * [More Examples](#More-Examples-2)
 * [Analyze Coverage](#Analyze-Coverage)
-* [Using Echoed without OpenTelemetry](#Using-Echoed-without-OpenTelemetry)
 
 # Jest
 
@@ -57,7 +67,7 @@ scenario:
               content-type: application/json
 ```
 
-For more details, refer to the [YAML documentation](/docs/yamlScenario.md).  
+For more details, refer to the [YAML documentation](/docs/yamlJestScenario.md).  
 
 ## TypeScript
 
@@ -155,8 +165,73 @@ describe("Awesome test", () => {
 
 For more examples, refer to [jest/example/test](../create-echoed/template/jest/example/test) directory.
 
+## Using Echoed without OpenTelemetry
+
+While Echoed's primary feature is to troubleshoot or analyze tests by visualizing OpenTelemetry data, it can also be used to write Jest tests in YAML.  
+
+To add YAML tests into existing Jest tests, simply create a `.echoed.yml` file for configuration.  
+In the [Installation](./installation.md), you may see `nodeEnvironment` and `reporter` is added in `jest.config.js`. However, because these configurations are to collect OpenTelemetry data, when you don't use OpenTelemetry, there's no need to modify it.
+
+Alternatively, if you wish to create example tests without OpenTelemetry, you can do so using the following commands:
+```bash
+# Create example tests
+npm create echoed@latest -- --template jest-no-otel
+
+# Compile YAML to TypeScript and run tests
+npx echoed compile
+npx jest
+```
+
 # Playwright
 
+## YAML
+
+You can write tests using YAML, and Echoed will convert them into Playwright tests.  
+![Compilation flow](https://github.com/mrasu/echoed/raw/main/docs/img/scenarioYamlToPlaywright.png)
+
+### Create Observable Tests
+
+The YAML below opens `http://localhost:8080` and validates DOM elements.
+
+```yaml
+scenarios:
+  - name: Validate Homepage
+    fixtures:
+      - page
+    steps:
+      - description: Check product list is shown
+        act:
+          raw: await page.goto("http://localhost:8080")
+        assert:
+          - expectToBeVisible: "[data-cy=home-page]"
+          - expectToHaveCount:
+              selector: "[data-cy=product-list] [data-cy=product-card]"
+              count: 10
+```
+
+To execute the test, use the command `npx echoed compile` to transform the YAML into TypeScript, and then run Playwright
+
+### Configuration
+
+To configure runners and adjust other options, include `scenario` block in the `.echoed.yml` file, like below:
+
+```yaml
+scenario:
+  compile:
+    targets:
+      - yamlDir: test/scenario
+        outDir: test/scenario_gen
+        type: playwright
+    env:
+      BASE_ENDPOINT: http://localhost:8080
+```
+
+For more details, refer to the [YAML documentation](/docs/yamlPlaywrightScenario.md).  
+
+## TypeScript
+
+You can write tests in TypeScript too.
+
 ### Make Tests Observable
 
 To generate an HTML report visualizing API traces, replace `test` of Playwright to Echoed's to intercept requests.
@@ -253,14 +328,27 @@ test("creates an OpenTelemetry span", async ({ request }) => {
 });
 ```
 
-## YAML
-
-YAML is under development. 🚧
-
 ## More Examples
 
 For more examples, refer to [playwright/example/test](../create-echoed/template/playwright/example/test) directory.
 
+## Using Echoed without OpenTelemetry
+
+While Echoed's primary feature is to troubleshoot or analyze tests by visualizing OpenTelemetry data, it can also be used to write Playwright tests in YAML.  
+
+To add YAML tests into existing Jest tests, simply create a `.echoed.yml` file for configuration.  
+In the [Installation](./installation.md), you may see `globalSetup` and `reporter` is added in `playwright.config.ts`. However, because these configurations are to collect OpenTelemetry data, when you don't use OpenTelemetry, there's no need to modify it.
+
+Alternatively, if you wish to create example tests without OpenTelemetry, you can do so using the following commands:
+```bash
+# Create example tests
+npm create echoed@latest -- --template playwright-no-otel
+
+# Compile YAML to TypeScript and run tests
+npx echoed compile
+npx playwright test
+```
+
 # Cypress
 
 ### Make Tests Observable
@@ -377,19 +465,3 @@ services:
       services:
         - oteldemo.CartService
 ```
-
-# Using Echoed without OpenTelemetry
-
-While Echoed's primary feature is to troubleshoot or analyze tests by visualizing OpenTelemetry data, it can also be used to write Jest tests in YAML.  
-To add Echoed into existing tests for writing tests in YAML, simply create a `.echoed.yml` file for configuration.  
-In the "Installation" section, you may see `nodeEnvironment` and `reporter` is added in `jest.config.js`. However, because these configurations are to collect OpenTelemetry data, when you don't use OpenTelemetry, there's no need to modify it.
-
-Alternatively, if you wish to create example tests without OpenTelemetry, you can do so using the following commands:
-```bash
-# Create example tests
-npm create echoed@latest -- --template jest-no-otel
-
-# Compile YAML to TypeScript and run tests
-npx echoed compile
-npx jest
-```

docs/scenario.md

@@ -0,0 +1,129 @@
+# Scenario(YAML)
+
+You can write tests in YAML, and Echoed will convert them into tests.  
+
+* [Supported frameworks](#supported-frameworks)
+* [Variable](#variable)
+* [Configuration](#configuration)
+* [Plugin](#plugin)
+  * [Built-in Plugins](#built-in-plugins)
+  * [Custom Plugin](#custom-plugin)
+
+## Supported frameworks
+Framework specific features are documented in the following documents:
+
+- [Jest](./yamlJestScenario.md)
+- [Playwright](./yamlPlaywrightScenario.md)
+
+## Variable
+
+In YAML, there are several predefined variables that you can use:
+
+* `_`: Represents the result of `act` in the current step. (in `arrange`, `_` is to reference the result of the current `arrange`.)
+* `_steps`: Represents the result of `act` in steps.  
+  You can access it by index, for example, `_steps[-1]` or `_steps[2]`. A negative index indicates the relative position from the current step, while a positive index signifies the absolute position starting with zero.
+* `_env`: Represents the environment variables defined in the configuration.
+* `_arranges`: Represents the result of `arrange` in the current step in `arrange` section.  
+  You can access it by index as same as `_steps`.
+
+## Configuration
+
+You can configure the behavior of the scenario by adding configuration like below at `.echoed.yml` file:
+
+```yaml
+scenario:
+  compile:
+    env:
+      BASE_ENDPOINT: http://localhost:8080 # <- You can enable the lookup of environment variables with/without default values.
+    plugin:
+      runners:
+        - name: fetch
+          module: echoed/scenario/gen/jest/runner
+          option:
+            baseEndpoint: ${_env.BASE_ENDPOINT}/api # <- You can reference environment variables with `_env`.
+            headers:
+              content-type: application/json
+      commons:  # <- You can import any module.
+        - names:
+            - createSession
+          module: "@/example/util/session"
+```
+This configuration example does following:
+
+* Sets the default value for the environment variable `BASE_ENDPOINT`.
+* Sets the default options for the `fetch` runner.
+* Imports `createSession` function from `@/example/util/session`.
+
+For more detailed information, refer to [configSchema.ts](../src/schema/configSchema.ts).
+
+## Plugin
+
+To extend scenarios with additional functionalities, you can add functions at `plugin` section in the `.echoed.yml` file.  
+There are three types of plugins: `Runner`, `Asserter` and `Common`.
+
+* `Runner`  
+    A function that is called inside `act` and `arrange`, typically performing actions like an HTTP request.  
+    Its result is stored in the `_` variable. 
+* `Asserter`  
+  A function that is called inside `assert`, taking two arguments, typically for the expected and actual values. 
+
+* `Common`  
+  A function or variable that is usable anywhere except sections for `Runner` and `Asserter`.  
+  Typically, it is called inside `${}`.
+
+### Built-in Plugins
+
+Some plugins are available by default.
+
+Refer to documents for corresponding framework for a full list of plugins.
+- Jest
+  - [jest/runner/index.ts](../src/scenario/gen/jest/runner/index.ts)
+  - [jest/asserter/index.ts](../src/scenario/gen/jest/asserter/index.ts)
+- Playwright
+  - [playwright/runner/index.ts](../src/scenario/gen/playwright/runner/index.ts)
+
+If the name of built-in plugin collides with other plugin, the non-built-in plugin will take precedence.
+
+### Custom Plugin
+
+You can easily create custom plugins by creating function implementing corresponding interface and configure them in the `plugin` section.
+
+* `Runner`  
+  To create a custom runner, implement a function following the `Runner` interface in `echoed/scenario/gen/jest/runner`.  
+  Here's an example:
+  ```ts
+  const myRunner = async (
+    ctx: EchoedContext,
+    argument: Argument,
+    option: Option,
+  ): Promise<Response> => {
+    return await myFunction(argument);
+  }
+  ```
+* `Asserter`  
+  To create a custom asserter, implement a function following the `Asserter` interface in `echoed/scenario/gen/jest/asserter`.  
+  Here's an example:
+  ```ts
+  const myAsserter = (
+    ctx: unknown,
+    expected: number,
+    actual: number,
+    option: Option,
+  ): void => {
+    expect(actual).toBe(expected);
+  }
+  ```
+
+To use custom plugins, add them at the `plugin` section in `.echoed.yml` file.  
+For instance, if you've created above plugins in `@/plugin`, configure them as follows:
+```yaml
+scenario:
+  compile:
+    plugin:
+      runner:
+        - name: myRunner
+          module: "@/plugin"
+      asserter:
+        - name: myAsserter
+          module: "@/plugin"
+```