feat: add @tag decorator

README.md

@@ -25,7 +25,7 @@ class MyTestSuite {
 
 ## 📝 Documentation
 ### Creating a test suite: `@suite(options?)`
-Decorate a class with `@suite()` or `@suite(options)` to create a test suite.
+Mark class as test suite.
 Under the hood, decorator creates a `describe` block and runs all methods decorated by `@test` inside it.
 
 ```ts
@@ -41,7 +41,7 @@ class MyTestSuite {
 - `name` (optional) - name of the test suite. By default, name of the class.
 
 ### Creating a test: `@test(options?)`
-Mark class method as test by decorating it with `@test()` or `@test(options)` decorator.
+Mark class method as test.
 Under the hood, decorator creates a `test` block and runs the method inside it.
 
 ```ts
@@ -120,7 +120,7 @@ class MyTestSuite {
 ```
 
 ### Skip test or suite: `@skip(reason?: string)`
-Skip single method or test suite.
+Skip single `@test` or `@suite`.
 
 ```ts
 import { suite, test, skip } from 'playwright-decorators';
@@ -146,7 +146,7 @@ class MyTestSuite {
 - `reason` (optional) - reason of skipping. Will be displayed in the test report.
 
 ### Mark test or suite as "slow": `@slow(reason?: string)`
-Mark single method or test suite as "slow".
+Mark single `@test` or `@suite` as "slow".
 Slow test will be given triple the default timeout.
 
 ```ts
@@ -173,7 +173,7 @@ class MyTestSuite {
 - `reason` (optional) - reason of marking as "slow". Will be displayed in the test report.
 
 ### Run only selected test(s) or suite(s): `@only()`
-Declares a focused test or suite.
+Declares a focused `@test` or `@suite`.
 If there are some focused tests or suites, all of them will be run but nothing else.
 
 ```ts
@@ -195,3 +195,36 @@ class TestSuite {
     }
 }
 ```
+
+### Run test(s) or suite(s) with certain tag(s): `@tag(tags: string[])`
+Adds tags to `@test` or `@suite`.
+You can later run test(s) or suite(s) with specific tag, using `npx playwright test --grep "@nameOfTag"` command.
+For example: to run tests/suites with `x` tag, please run `npx playwright test --grep "@x"`
+
+```ts
+import { suite, test, tag } from 'playwright-decorators';
+
+// Run only selected test suite(s)
+@tag(['x-api-consumer']) // <-- Decorate suite with @tag()
+@suite()
+class ApiConsumerTestSuite {
+}
+
+// Or run only selected test(s)
+@suite()
+class TestSuite {
+    @tag(['x-api-consumer']) // <-- Decorate test with @tag()
+    @test()
+    async apiConsumerTest({ page }) {
+        // ...
+    }
+}
+```
+
+To run test(s) or suite(s) for `x-api-consumer` tag (example above), please type and run below command:
+```shell
+npx playwright test --grep "@x-api-consumer"
+``` 
+
+#### Options
+- `tags` (required) - array of tags. (Tags should not be prefixed with `@` sign, as sign will be automatically added to every tag by `@tag` decorator).

lib/index.ts

@@ -10,3 +10,5 @@ export { afterEach } from './afterEach.decorator';
 export { skip } from './skip.decorator';
 export { slow } from './slow.decorator';
 export { only } from './only.decorator';
+// helpers
+export { tag } from './tag.decorator';

lib/tag.decorator.ts

@@ -0,0 +1,21 @@
+import {SuiteDecoratedMethod} from "./suite.decorator";
+import {TestDecoratedMethod} from "./test.decorator";
+
+/**
+ * Adds tags to `@test` or `@suite`.
+ * You can later run test(s) or suite(s) with specific tag, using `npx playwright test --grep "@nameOfTag"` command.
+ * For example: to run tests/suites with `x` tag, please run `npx playwright test --grep "@x"`
+ */
+export const tag = (tags: string[]) => function(originalMethod: any, context?: any) {
+  const tagsAsPlaywrightAnnotations = tags.map(tag => `@${tag}`).join(' ');
+
+  if ((originalMethod as SuiteDecoratedMethod)?.suiteDecorator) {
+    originalMethod.suiteDecorator.name = `${originalMethod.suiteDecorator.name} ${tagsAsPlaywrightAnnotations}`;
+    return;
+  }
+
+  if ((originalMethod as TestDecoratedMethod)?.testDecorator) {
+    originalMethod.testDecorator.name = `${originalMethod.testDecorator.name} ${tagsAsPlaywrightAnnotations}`;
+    return;
+  }
+}

tests/tag.spec.ts

@@ -0,0 +1,41 @@
+import playwright, {expect} from "@playwright/test";
+import {mockFn} from "./__mocks__/mockFn";
+import {suite, tag, test} from "../lib";
+
+playwright.describe('@tag decorator', () => {
+  playwright.describe('with @suite', () => {
+    const titlePath: string[] = [];
+
+    @tag(['x'])
+    @suite()
+    class SuiteWithTag {
+      @test()
+      async test({}, testInfo) {
+        titlePath.push(...testInfo.titlePath);
+      }
+    }
+
+    playwright('should add @x tag to suite name', () => {
+      expect(titlePath.join('->')).toContain('SuiteWithTag');
+      expect(titlePath.join('->')).toContain('@x');
+    });
+  })
+
+  playwright.describe('with @test', () => {
+    const titlePath: string[] = [];
+
+    @suite()
+    class TestSuite {
+      @tag(['x'])
+      @test()
+      async testWithTag({}, testInfo) {
+        titlePath.push(...testInfo.titlePath);
+      }
+    }
+
+    playwright('should add @x tag to test name', () => {
+      expect(titlePath.join('->')).toContain('testWithTag');
+      expect(titlePath.join('->')).toContain('@x');
+    });
+  });
+});