feat: support suite.skip and suite.only (#518)

README.md

@@ -70,6 +70,15 @@ tests.integration(path.join(__dirname, ".."), {
 				});
 			});
 		});
+
+		// While developing the tests, you can run only a single suite using `suite.only`...
+		suite.only("Only this will run", (getHarness) => {
+			// ...
+		});
+		// ...or prevent a suite from running using `suite.skip`:
+		suite.skip("This will never run", (getHarness) => {
+			// ...
+		});
 	},
 });
 ```

build/tests/integration/index.d.ts

@@ -10,14 +10,23 @@ export interface TestAdapterOptions {
     /** Allows you to define additional tests */
     defineAdditionalTests?: (args: TestContext) => void;
 }
+export interface TestSuiteFn {
+    (name: string, fn: (getHarness: () => TestHarness) => void): void;
+}
+export interface TestSuite extends TestSuiteFn {
+    /** Only runs the tests inside this `suite` for the current file */
+    only: TestSuiteFn;
+    /** Skips running the tests inside this `suite` for the current file */
+    skip: TestSuiteFn;
+}
 export interface TestContext {
     /**
      * Defines a test suite. At the start of each suite, the adapter will be started with a fresh environment.
      * To define tests in each suite, use describe and it as usual.
      *
-     * Each suite has its own test harness, which gets passed as an argument.
+     * Each suite has its own test harness, which can be retrieved using the function that is passed to the suite callback.
      */
-    suite: (name: string, fn: (getHarness: () => TestHarness) => void) => void;
+    suite: TestSuite;
     describe: Mocha.SuiteFunction;
     it: Mocha.TestFunction;
 }

build/tests/integration/index.js

@@ -175,17 +175,26 @@ function testAdapter(adapterDir, options = {}) {
             describe("User-defined tests", () => {
                 // patch the global it() function so nobody can bypass the checks
                 global.it = patchedIt;
+                // a test suite is a special describe which sets up and tears down the test environment before and after ALL tests
+                const suiteBody = (fn) => {
+                    isInSuite = true;
+                    before(resetDbAndStartHarness);
+                    fn(() => harness);
+                    after(shutdownTests);
+                    isInSuite = false;
+                };
+                const suite = ((name, fn) => {
+                    describe(name, () => suiteBody(fn));
+                });
+                // Support .skip and .only
+                suite.skip = (name, fn) => {
+                    describe.skip(name, () => suiteBody(fn));
+                };
+                suite.only = (name, fn) => {
+                    describe.only(name, () => suiteBody(fn));
+                };
                 const args = {
-                    // a test suite is a special describe which sets up and tears down the test environment before and after ALL tests
-                    suite: (name, fn) => {
-                        describe(name, () => {
-                            isInSuite = true;
-                            before(resetDbAndStartHarness);
-                            fn(() => harness);
-                            after(shutdownTests);
-                            isInSuite = false;
-                        });
-                    },
+                    suite,
                     describe,
                     it: patchedIt,
                 };

src/tests/integration/index.ts

@@ -18,14 +18,25 @@ export interface TestAdapterOptions {
 	defineAdditionalTests?: (args: TestContext) => void;
 }
 
+export interface TestSuiteFn {
+	(name: string, fn: (getHarness: () => TestHarness) => void): void;
+}
+
+export interface TestSuite extends TestSuiteFn {
+	/** Only runs the tests inside this `suite` for the current file */
+	only: TestSuiteFn;
+	/** Skips running the tests inside this `suite` for the current file */
+	skip: TestSuiteFn;
+}
+
 export interface TestContext {
 	/**
 	 * Defines a test suite. At the start of each suite, the adapter will be started with a fresh environment.
 	 * To define tests in each suite, use describe and it as usual.
 	 *
 	 * Each suite has its own test harness, which can be retrieved using the function that is passed to the suite callback.
 	 */
-	suite: (name: string, fn: (getHarness: () => TestHarness) => void) => void;
+	suite: TestSuite;
 
 	describe: Mocha.SuiteFunction;
 	it: Mocha.TestFunction;
@@ -230,19 +241,37 @@ export function testAdapter(
 				// patch the global it() function so nobody can bypass the checks
 				global.it = patchedIt;
 
-				const args: TestContext = {
-					// a test suite is a special describe which sets up and tears down the test environment before and after ALL tests
-					suite: (name, fn) => {
-						describe(name, () => {
-							isInSuite = true;
-							before(resetDbAndStartHarness);
+				// a test suite is a special describe which sets up and tears down the test environment before and after ALL tests
+				const suiteBody = (
+					fn: (getHarness: () => TestHarness) => void,
+				): void => {
+					isInSuite = true;
+					before(resetDbAndStartHarness);
 
-							fn(() => harness);
+					fn(() => harness);
 
-							after(shutdownTests);
-							isInSuite = false;
-						});
-					},
+					after(shutdownTests);
+					isInSuite = false;
+				};
+
+				const suite = ((
+					name: string,
+					fn: (getHarness: () => TestHarness) => void,
+				): void => {
+					describe(name, () => suiteBody(fn));
+				}) as TestSuite;
+
+				// Support .skip and .only
+				suite.skip = (name, fn) => {
+					describe.skip(name, () => suiteBody(fn));
+				};
+
+				suite.only = (name, fn) => {
+					describe.only(name, () => suiteBody(fn));
+				};
+
+				const args: TestContext = {
+					suite,
 					describe,
 					it: patchedIt,
 				};