--filter-path= option to do exact (non-regex) prefix filtering

Author: sgravrock

lib/command.js

@@ -92,7 +92,8 @@ function parseOptions(argv, isWindows) {
   let color = process.stdout.isTTY || false;
   let reporter;
   let configPath;
-  let filter;
+  let filterRegex;
+  let filterPath;
   let failFast;
   let random;
   let seed;
@@ -105,7 +106,18 @@ function parseOptions(argv, isWindows) {
     } else if (arg === '--color') {
       color = true;
     } else if (arg.match("^--filter=")) {
-      filter = arg.match("^--filter=(.*)")[1];
+      filterRegex = arg.match("^--filter=(.*)")[1];
+    } else if (arg.match("^--filter-path=(.*)")) {
+      const json = arg.match("^--filter-path=(.*)")[1];
+      try {
+        filterPath = JSON.parse(json);
+      } catch {
+        usageErrors.push('Invalid filter path: ' + json);
+      }
+
+      if (!(filterPath instanceof Array)) {
+        usageErrors.push('Invalid filter path: ' + json);
+      }
     } else if (arg.match("^--helper=")) {
       helpers.push(arg.match("^--helper=(.*)")[1]);
     } else if (arg.match("^--require=")) {
@@ -142,14 +154,19 @@ function parseOptions(argv, isWindows) {
     }
   }
 
+  if (numWorkers > 1 && filterPath) {
+    usageErrors.push('--filter-path is not supported in parallel mode.');
+  }
+
   if (unknownOptions.length > 0) {
     usageErrors.push('Unknown options: ' + unknownOptions.join(', '));
   }
 
   return {
     color,
     configPath,
-    filter,
+    filterRegex,
+    filterPath,
     failFast,
     helpers,
     requires,
@@ -209,8 +226,16 @@ async function runJasmine(Jasmine, ParallelRunner, projectBaseDir, options) {
 
   runner.showColors(options.color);
 
+  let filter;
+
+  if (options.filterRegex) {
+    filter = options.filterRegex;
+  } else if (options.filterPath) {
+    filter = {path: options.filterPath};
+  }
+
   try {
-    await runner.execute(options.files, options.filter);
+    await runner.execute(options.files, filter);
   } catch (error) {
     console.error(error);
     process.exit(1);
@@ -319,6 +344,9 @@ function help(deps) {
     { syntax: '--no-color', help: 'turn off color in spec output' },
     { syntax: '--color', help: 'force turn on color in spec output' },
     { syntax: '--filter=', help: 'filter specs to run only those that match the given regular expression' },
+    { syntax: '--filter-path=', help: 'run only the spec or suite that matches ' +
+        'the given path, e.g. ' +
+        '--filter-path=\'["parent suite name","child suite name","spec name"]\'' },
     { syntax: '--helper=', help: 'load helper files that match the given string' },
     { syntax: '--require=', help: 'load module that matches the given string' },
     { syntax: '--fail-fast', help: 'stop Jasmine execution on spec failure' },

lib/filters/path_spec_filter.js

@@ -0,0 +1,19 @@
+module.exports = exports = pathSpecFilter;
+
+function pathSpecFilter(filterPath) {
+  return function(spec) {
+    const specPath = spec.getPath();
+
+    if (filterPath.length > specPath.length) {
+      return false;
+    }
+
+    for (let i = 0; i < filterPath.length; i++) {
+      if (specPath[i] !== filterPath[i]) {
+        return false;
+      }
+    }
+
+    return true;
+  };
+}

lib/jasmine.js

@@ -1,5 +1,6 @@
 const ExitHandler = require('./exit_handler');
 const regexSpecFilter = require('./filters/regex_spec_filter');
+const pathSpecFilter = require('./filters/path_spec_filter');
 const RunnerBase = require('./runner_base');
 
 /**
@@ -181,11 +182,29 @@ class Jasmine extends RunnerBase {
    * ordinarily exit before the promise is settled.
    * @param {Array.<string>} [files] Spec files to run instead of the previously
    * configured set
-   * @param {string} [filterString] Regex used to filter specs. If specified, only
+   * @param {string|object} [filter] Optional specification of what specs to run.
+   * Can be either a string or an object. If it's a string, it will be
+   * interpreted as a regex that matches the full names of specs to run. If it's
+   * an object, it should have a path property whose value is an array of spec
+   * or suite descriptions.
+   * Regex used to filter specs. If specified, only
    * specs with matching full names will be run.
    * @return {Promise<JasmineDoneInfo>} Promise that is resolved when the suite completes.
+   * @example
+   * // Run all specs
+   * await jasmine.execute();
+   *
+   * // Run just spec/someSpec.js
+   * await jasmine.execute(['spec/someSpec.js']);
+   *
+   * // Run all specs with full paths starting with "a suite a child suite"
+   * await jasmine.execute(null, '^a suite a child suite');
+   *
+   * // Run all specs that are inside a suite named "a child suite" that is
+   * // inside a top-level suite named "a suite"
+   * await jasmine.execute(null, {path: ['a suite', 'a child suite']});
    */
-  async execute(files, filterString) {
+  async execute(files, filter) {
     await this.loadRequires();
     await this.loadHelpers();
     if (!this.defaultReporterConfigured) {
@@ -195,10 +214,18 @@ class Jasmine extends RunnerBase {
       });
     }
 
-    if (filterString) {
-      this.env.configure({
-        specFilter: regexSpecFilter(filterString)
-      });
+    if (filter) {
+      if (typeof filter === 'string') {
+        this.env.configure({
+          specFilter: regexSpecFilter(filter)
+        });
+      } else if (filter.path) {
+        this.env.configure({
+          specFilter: pathSpecFilter(filter.path)
+        });
+      } else {
+        throw new Error('Unrecognized filter type');
+      }
     }
 
     if (files && files.length > 0) {

package.json

@@ -32,7 +32,7 @@
   ],
   "dependencies": {
     "glob": "^10.2.2",
-    "jasmine-core": "~5.5.0"
+    "jasmine-core": "github:jasmine/jasmine"
   },
   "bin": "./bin/jasmine.js",
   "main": "./lib/jasmine.js",

spec/command_spec.js

@@ -507,6 +507,26 @@ describe('command', function() {
           stopSpecOnExpectationFailure: true
         });
       });
+
+      describe('Path filtering', function() {
+        it('should be able to filter by path', async function () {
+          await this.run(['--filter-path=["a","b","c"]']);
+          expect(this.runner.execute).toHaveBeenCalledWith(jasmine.any(Array),
+            {path: ['a', 'b', 'c']});
+        });
+
+        it('rejects invalid JSON', async function() {
+          await this.run(['--filter-path=not valid JSON']);
+          const output = this.out.getOutput();
+          expect(output).toContain('Invalid filter path: not valid JSON');
+        });
+
+        it('rejects non-arrays', async function() {
+          await this.run(['--filter-path={}}']);
+          const output = this.out.getOutput();
+          expect(output).toContain('Invalid filter path: {}}');
+        });
+      });
     });
 
     describe('In parallel mode', function() {
@@ -515,6 +535,13 @@ describe('command', function() {
       });
 
       sharedRunBehavior('--parallel=2');
+
+      it('rejects --filter-path', async function() {
+        await this.run(['--filter-path=[]', '--parallel=2']);
+        const output = this.out.getOutput();
+        expect(output).toContain(
+          '--filter-path is not supported in parallel mode.');
+      });
     });
   });
 

spec/jasmine_spec.js

@@ -229,32 +229,61 @@ describe('Jasmine', function() {
       expect(this.testJasmine.configureDefaultReporter).toHaveBeenCalled();
     });
 
-    describe('When a filter string is provided', function() {
-      it('installs a matching spec filter', async function() {
-        let specFilter;
-        this.testJasmine.env.configure.and.callFake(function(config) {
+    describe('Filtering', function() {
+      let specFilter;
+
+      beforeEach(function() {
+        this.testJasmine.env.configure.and.callFake(function (config) {
           if (config.specFilter) {
             specFilter = config.specFilter;
           }
         });
+      });
 
-        await this.execute({
-          executeArgs: [['spec/fixtures/example/*spec.js'], 'interesting spec']
+      describe('When a filter string is provided', function () {
+        it('installs a matching spec filter', async function () {
+          await this.execute({
+            executeArgs: [['spec/fixtures/example/*spec.js'], 'interesting spec']
+          });
+
+          expect(specFilter).toBeTruthy();
+          const matchingSpec = {
+            getFullName() {
+              return 'this is an interesting spec that should match';
+            }
+          };
+          const nonMatchingSpec = {
+            getFullName() {
+              return 'but this one is not';
+            }
+          };
+          expect(specFilter(matchingSpec)).toBeTrue();
+          expect(specFilter(nonMatchingSpec)).toBeFalse();
         });
+      });
 
-        expect(specFilter).toBeTruthy();
-        const matchingSpec = {
-          getFullName() {
-            return 'this is an interesting spec that should match';
-          }
-        };
-        const nonMatchingSpec = {
-          getFullName() {
-            return 'but this one is not';
+      describe('When a path filter specification is provided', function () {
+        it('installs a matching spec filter', async function () {
+          await this.execute({
+            executeArgs: [['spec/fixtures/example/*spec.js'], {
+              path: ['parent', 'child', 'spec']
+            }]
+          });
+
+          function stubSpec(path) {
+            return {
+              getPath() { return path; },
+              // getFullName is required, but plays no role in filtering
+              getFullName() { return ""; }
+            };
           }
-        };
-        expect(specFilter(matchingSpec)).toBeTrue();
-        expect(specFilter(nonMatchingSpec)).toBeFalse();
+
+          expect(specFilter).toBeTruthy();
+          expect(specFilter(stubSpec(['parent', 'child', 'spec'])))
+            .toBeTrue();
+          expect(specFilter(stubSpec(['parent', 'other child', 'spec'])))
+            .toBeFalse();
+        });
       });
     });
 
@@ -443,8 +472,6 @@ describe('Jasmine', function() {
   });
 
   describe('#enumerate', function() {
-    it('does not run global setup');
-
     it('loads requires, helpers, and specs', async function() {
       const loadRequires = spyOn(this.testJasmine, 'loadRequires');
       const loadHelpers = spyOn(this.testJasmine, 'loadHelpers');

spec/path_spec_filter_spec.js

@@ -0,0 +1,26 @@
+const pathSpecFilter = require('../lib/filters/path_spec_filter');
+
+describe("pathSpecFilter", function() {
+  it("matches a spec with the exact same path", function() {
+    const specFilter = pathSpecFilter(["a", "b", "c"]);
+    expect(specFilter(stubSpec(['a', 'b', 'c']))).toBeTrue();
+  });
+
+  it('matches a spec whose path has the filter path as a prefix', function() {
+    const specFilter = pathSpecFilter(["a", "b"]);
+    expect(specFilter(stubSpec(['a', 'b', 'c']))).toBeTrue();
+  });
+
+  it('does not match a spec with a different path', function() {
+    const specFilter = pathSpecFilter(["a", "b", "c"]);
+    expect(specFilter(stubSpec(['a', 'd', 'c']))).toBeFalse();
+  });
+
+  function stubSpec(path) {
+    return {
+      getPath() { return path; },
+      // getFullName is required, but plays no role in filtering
+      getFullName() { return ""; }
+    };
+  }
+});