feat(testlab): add generic helper skipOnTravis

Introduce a generic helper `skipOnTravis` that supports arbitrary
BDD verbs (`it`, `describe`, etc.) in a test-framework-agnostic way.

Rework `itSkippedOnTravis` to leverage the new helper and deprecate it
(in tsdocs only).

Signed-off-by: Miroslav Bajtoš <[email protected]>

Author: bajtos

packages/http-server/src/__tests__/integration/http-server.integration.ts

@@ -8,7 +8,7 @@ import {
   givenHttpServerConfig,
   httpGetAsync,
   httpsGetAsync,
-  itSkippedOnTravis,
+  skipOnTravis,
   supertest,
 } from '@loopback/testlab';
 import * as fs from 'fs';
@@ -22,7 +22,7 @@ describe('HttpServer (integration)', () => {
 
   afterEach(stopServer);
 
-  itSkippedOnTravis('formats IPv6 url correctly', async () => {
+  skipOnTravis(it, 'formats IPv6 url correctly', async () => {
     server = new HttpServer(dummyRequestHandler, {
       host: '::1',
     } as HttpOptions);
@@ -164,7 +164,7 @@ describe('HttpServer (integration)', () => {
     expect(response.statusCode).to.equal(200);
   });
 
-  itSkippedOnTravis('supports HTTP over IPv6', async () => {
+  skipOnTravis(it, 'supports HTTP over IPv6', async () => {
     server = new HttpServer(dummyRequestHandler, {host: '::1'});
     await server.start();
     expect(getAddressFamily(server)).to.equal('IPv6');
@@ -190,7 +190,7 @@ describe('HttpServer (integration)', () => {
     expect(response.statusCode).to.equal(200);
   });
 
-  itSkippedOnTravis('handles IPv6 loopback address in HTTPS', async () => {
+  skipOnTravis(it, 'handles IPv6 loopback address in HTTPS', async () => {
     const httpsServer: HttpServer = givenHttpsServer({
       host: '::1',
     });

packages/rest/src/__tests__/integration/rest.server.integration.ts

@@ -10,7 +10,7 @@ import {
   expect,
   givenHttpServerConfig,
   httpsGetAsync,
-  itSkippedOnTravis,
+  skipOnTravis,
   supertest,
 } from '@loopback/testlab';
 import * as fs from 'fs';
@@ -705,7 +705,7 @@ paths:
     await server.stop();
   });
 
-  itSkippedOnTravis('handles IPv6 loopback address in HTTPS', async () => {
+  skipOnTravis(it, 'handles IPv6 loopback address in HTTPS', async () => {
     const keyPath = path.join(FIXTURES, 'key.pem');
     const certPath = path.join(FIXTURES, 'cert.pem');
     const server = await givenAServer({
@@ -726,7 +726,7 @@ paths:
   });
 
   // https://github.com/strongloop/loopback-next/issues/1623
-  itSkippedOnTravis('handles IPv6 address for API Explorer UI', async () => {
+  skipOnTravis(it, 'handles IPv6 address for API Explorer UI', async () => {
     const keyPath = path.join(FIXTURES, 'key.pem');
     const certPath = path.join(FIXTURES, 'cert.pem');
     const server = await givenAServer({

packages/testlab/README.md

@@ -47,7 +47,7 @@ Table of contents:
 - [sinon](#sinon) - Mocks, stubs and more.
 - [shot](#shot) - HTTP Request/Response stubs.
 - [validateApiSpec](#validateapispec) - Open API Spec validator.
-- [itSkippedOnTravis](#itskippedontravis) - Skip tests on Travis env.
+- [skipOnTravis](#skipontravis) - Skip tests on Travis env.
 - [createRestAppClient](#createrestappclient) - Create a supertest client
   connected to a running RestApplication.
 - [givenHttpServerConfig](#givenhttpserverconfig) - Generate HTTP server config.
@@ -82,10 +82,21 @@ by Shot in your unit tests:
 - Code modifying core HTTP Response, including full request/response handlers
 - Code parsing Express HTTP Request or modifying Express HTTP Response
 
-### `itSkippedOnTravis`
+### `skipOnTravis`
 
 Helper function for skipping tests on Travis environment. If you need to skip
-testing on Travis for any reason, use this instead of Mocha's `it`.
+testing on Travis for any reason, use this helper together with `it` or
+`describe`.
+
+```ts
+skipOnTravis(it, 'does something when some condition', async () => {
+  // the test code
+});
+```
+
+Under the hood, `skipOnTravis` invokes the provided test verb by default (e.g.
+`it`). When the helper detects Travis CI environment variables, then it calls
+`.skip` instead (e.g. `it.skip`).
 
 ### `createRestAppClient`
 

packages/testlab/src/skip-travis.ts

@@ -3,6 +3,47 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A function defining a new test case or a test suite, e.g. `it` or `describe`.
+ */
+export type TestDefinition<ARGS extends unknown[], RETVAL> = (
+  name: string,
+  ...args: ARGS
+) => RETVAL;
+
+/**
+ * Helper function for skipping tests on Travis CI.
+ *
+ * @example
+ *
+ * ```ts
+ * skipOnTravis(it, 'does something when some condition', async () => {
+ *   // the test
+ * });
+ * ```
+ *
+ * @param verb - The function to invoke to define the test case or the test
+ * suite, e.g. `it` or `describe`.
+ * @param name - The test name (the first argument of `verb` function).
+ * @param args - Additional arguments (framework specific), typically a function
+ * implementing the test.
+ */
+export function skipOnTravis<ARGS extends unknown[], RETVAL>(
+  verb: TestDefinition<ARGS, RETVAL> & {skip: TestDefinition<ARGS, RETVAL>},
+  name: string,
+  ...args: ARGS
+): RETVAL {
+  if (process.env.TRAVIS) {
+    return verb.skip(`[SKIPPED ON TRAVIS] ${name}`, ...args);
+  } else {
+    return verb(name, ...args);
+  }
+}
+
+/*** LEGACY API FOR BACKWARDS COMPATIBILITY ***/
+
+// TODO(semver-major) remove this code
+
 // Simplified test function type from Mocha
 export interface TestFn {
   (this: TestContext): PromiseLike<unknown>;
@@ -18,21 +59,19 @@ export interface TestContext {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [index: string]: any;
 }
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type TestCallbackRetval = void | PromiseLike<any>;
 
 /**
- * Helper function for skipping tests on Travis env
- * @param expectation
- * @param callback
+ * Helper function for skipping tests on Travis env - legacy variant
+ * supporting `it` only.
+ *
+ * @param expectation - The test name (the first argument of `it` function).
+ * @param callback - The test function (the second argument of `it` function).
+ *
+ * @deprecated Use `skipOnTravis(it, name, fn)` instead.
  */
 export function itSkippedOnTravis(
   expectation: string,
   callback?: TestFn,
 ): void {
-  if (process.env.TRAVIS) {
-    it.skip(`[SKIPPED ON TRAVIS] ${expectation}`, callback);
-  } else {
-    it(expectation, callback);
-  }
+  skipOnTravis(it, expectation, callback);
 }