feat: add @Preview decorator (#42)

* feat: add `@preview` decorator

* chore: generate changeset

* chore: revert changes in examples configuration

.changeset/ninety-pants-speak.md

@@ -5,7 +5,7 @@
 Add `@debug` decorator
 
 Runs a `@test`(s) or `@suite`(s) in debug mode.
-`@test`(s) or `@suite`(s) lacking the `@debug` decorator will be excluded.
+Tests or suites without the `@debug` decorator will not be excluded.
 Learn more about debug mode: https://playwright.dev/docs/debug
 
 ```ts

.changeset/stale-avocados-mix.md

@@ -0,0 +1,28 @@
+---
+'playwright-decorators': minor
+---
+
+Add `@preview` decorator
+
+Runs a `@test`(s) or `@suite`(s) in preview (headed browser) mode, simulating user interaction (slowing down each operation by 1000ms).
+Tests or suites without the `@preview` decorator will not be excluded.
+
+```ts
+import { suite, test, preview, TestArgs } from 'playwright-decorators';
+
+// Preview selected test suite(s)
+@preview() // <-- Decorate suite with @preview()
+@suite()
+class PreviewTestSuite {
+}
+
+// Or preview selected test(s)
+@suite()
+class TestSuite {
+    @preview() // <-- Decorate test with @preview()
+    @test()
+    async test({ page }: TestArgs) {
+        // ...
+    }
+}
+```

README.md

@@ -337,7 +337,7 @@ class MyTestSuite {
 
 ### Run test(s) or suite(s) in debug mode: `@debug()`
 Runs a `@test`(s) or `@suite`(s) in debug mode.
-`@test`(s) or `@suite`(s) lacking the `@debug` decorator will be excluded.
+Tests or suites without the `@debug` decorator will not be excluded.
 Learn more about debug mode: https://playwright.dev/docs/debug
 
 ```ts
@@ -361,7 +361,36 @@ class TestSuite {
 ```
 
 Then run playwright tests as usual, i.e. `npx playwright test`.
-> For debugging purposes, running tests only for one project/browser is recommended.
+> For debugging purposes, running tests only on local machine for one project/browser is recommended.
+
+
+### Run test(s) or suite(s) in preview mode: `@preview()`
+Runs a `@test`(s) or `@suite`(s) in preview (headed browser) mode, simulating user interaction (slowing down each operation by 1000ms).
+Tests or suites without the `@preview` decorator will not be excluded.
+
+```ts
+import { suite, test, preview, TestArgs } from 'playwright-decorators';
+
+// Preview selected test suite(s)
+@preview() // <-- Decorate suite with @preview()
+@suite()
+class PreviewTestSuite {
+}
+
+// Or preview selected test(s)
+@suite()
+class TestSuite {
+    @preview() // <-- Decorate test with @preview()
+    @test()
+    async test({ page }: TestArgs) {
+        // ...
+    }
+}
+```
+
+Then run playwright tests as usual, i.e. `npx playwright test`.
+> For preview purposes, running tests only for one project/browser is recommended.
+
 
 ### Custom decorators
 Custom decorators can be created using `createTestDecorator` and `createSuiteDecorator` functions.

lib/debug.decorator.ts

@@ -2,7 +2,7 @@ import { createSuiteAndTestDecorator } from './custom'
 
 /**
  * Runs a @test or @suite in debug mode.
- * @test(s) or @suite(s) lacking the @debug decorator will be excluded.
+ * Tests or suites without the @debug decorator will not be excluded.
  * Learn more about debug mode: https://playwright.dev/docs/debug
  */
 export const debug = () =>

lib/index.ts

@@ -23,6 +23,7 @@ export { tag } from './tag.decorator'
 
 // helpers
 export { debug } from './debug.decorator'
+export { preview } from './preview.decorator'
 
 // common
 export { type TestInfo, type TestArgs } from './common'

lib/preview.decorator.ts

@@ -0,0 +1,33 @@
+import { createSuiteAndTestDecorator } from './custom'
+import playwright from '@playwright/test'
+
+const playwrightPreviewPreset = () => {
+  // disable timeout, as all operations are slowed down by 1000ms
+  playwright.describe.configure({ timeout: 0 })
+
+  playwright.use({
+    // enable headed mode
+    headless: false,
+    launchOptions: {
+      // slow down every operation by 1000ms
+      slowMo: 1000
+    }
+  })
+}
+
+/**
+ * Runs a @test(s) or @suite(s) in preview (headed browser) mode, simulating user interaction (slowing down each operation by 1000ms).
+ * Tests or suites without the @preview decorator will not be excluded.
+ */
+export const preview = () =>
+  createSuiteAndTestDecorator(
+    'preview',
+    ({ suite }) => {
+      playwrightPreviewPreset()
+      suite.only = true
+    },
+    ({ test }) => {
+      playwrightPreviewPreset()
+      test.only = true
+    }
+  )