ember-testem 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,243 @@
 # ember-testem
 
-_Forward- and backward-compatible testing for Ember projects_
+_Backward- and forward-compatible testing for Ember projects_
+
+
+## Quickstart
+
+1\. Install `ember-testem` as a development dependency. The package provides an executable named `ember-test`.
+
+```sh
+pnpm add -D ember-testem
+```
+
+2\. Configure `testem` in `testem.mjs`.
+
+```js
+export default {
+  browser_args: {
+    Chrome: {
+      ci: [
+        // --no-sandbox is needed when running Chrome inside a container
+        process.env.CI ? '--no-sandbox' : null,
+        '--headless',
+        '--disable-dev-shm-usage',
+        '--disable-software-rasterizer',
+        '--mute-audio',
+        '--remote-debugging-port=0',
+        '--window-size=1440,900',
+      ].filter(Boolean),
+    },
+  },
+  browser_start_timeout: 120,
+  disable_watching: true,
+  launch_in_ci: ['Chrome'],
+  launch_in_dev: ['Chrome'],
+  test_page: 'tests/index.html?hidepassed&nolint',
+};
+```
+
+3\. Update the `test` script in `package.json` so that it separates concerns. Build the test app, then run it.
+
+```diff
+{
+  "scripts": {
+    "build": "..."
++     "build:test": "...",
+-     "test": "ember test"
++     "test": "pnpm build:test && ember-test"
++     "test:watch": "concurrently \"pnpm build:test --watch\" && \"pnpm ember-test --server\" --names build,test"
+  },
+  "devDependencies": {
+    "concurrently": "...",
++     "ember-testem": "..."
+  }
+}
+```
+
+Note, `test:watch` can encounter race conditions. Once the test build is complete, refresh the test browser to see the latest results.
+
+<details>
+
+<summary>V1 addons</summary>
+
+See [my-v1-addon](../../tests/my-v1-addon) for an example.
+
+```json
+{
+  "scripts": {
+    "build": "ember build --environment production",
+    "build:test": "ember build --environment test"
+  }
+}
+```
+
+</details>
+
+<details>
+
+<summary>V1 apps</summary>
+
+See [my-v1-app](../../tests/my-v1-app) for an example.
+
+```json
+{
+  "scripts": {
+    "build": "ember build --environment production",
+    "build:test": "ember build --environment test"
+  }
+}
+```
+
+</details>
+
+<details>
+
+<summary>V2 addons</summary>
+
+See [my-v2-addon](../../tests/my-v2-addon) for an example.
+
+For brevity, additional file changes aren't shown below. For example, you will need to split the Babel and TypeScript configurations into two files: one for production and another for testing.
+
+```json
+{
+  "scripts": {
+    "build": "rollup --config",
+    "build:test": "NODE_ENV=development vite build --config vite.test.config.mts --mode development"
+  }
+}
+```
+
+```ts
+/* vite.test.config.mts */
+import { extensions, ember } from '@embroider/vite';
+import { babel } from '@rollup/plugin-babel';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    minify: false,
+    rollupOptions: {
+      input: {
+        tests: 'tests/index.html',
+      },
+    },
+    sourcemap: true,
+  },
+  plugins: [
+    ember(),
+    babel({
+      babelHelpers: 'inline',
+      extensions,
+      parallel: true,
+    }),
+  ],
+});
+```
+
+</details>
+
+<details>
+
+<summary>V2 apps</summary>
+
+See [my-v2-app](../../tests/my-v2-app) for an example.
+
+```json
+{
+  "scripts": {
+    "build": "vite build",
+    "build:test": "NODE_ENV=development vite build --config vite.test.config.mts --mode development"
+  }
+}
+```
+
+```ts
+/* vite.test.config.mts */
+import { defineConfig } from 'vite';
+
+import baseConfiguration from './vite.config.mts';
+
+export default defineConfig({
+  ...baseConfiguration,
+  build: {
+    minify: false,
+    sourcemap: true,
+  },
+});
+```
+
+</details>
+
+
+### Arguments
+
+<details>
+
+<summary>Optional: Launch test browser</summary>
+
+Pass `--server` (`-s`) to launch a browser. This may be useful for debugging (e.g. with `debugger` or `await this.pauseTest()`) and re-running the tests after a code change (don't forget to pass `--watch` to `build:test`).
+
+```sh
+ember-test --server
+```
+
+</details>
+
+<details>
+
+<summary>Optional: Specify filters for QUnit</summary>
+
+The `--module` (`-m`) option allows you to select a module—a group of tests inside a `module()`.
+
+```sh
+ember-test --module "Integration | Component | ui/form/input"
+```
+
+The `--filter` (`-f`) is more versatile. You can provide a keyword to match against the modules and test descriptions. A test description is what appears in `test()`.
+
+```sh
+ember-test --filter integration
+ember-test --filter ui/form
+# Exclude acceptance tests
+ember-test --filter \!acceptance
+```
+
+</details>
+
+<details>
+
+<summary>Optional: Specify path to test build</summary>
+
+By default, `ember-testem` assumes `dist` to be the path to the test build.
+
+Pass `--path` to indicate otherwise. This may be useful if you want to create the production and test builds in different locations.
+
+```sh
+ember-test --path dist-for-testing
+```
+
+</details>
+
+<details>
+
+<summary>Optional: Specify test port</summary>
+
+By default, `ember-testem` runs tests on port `7357`.
+
+Pass `--port` (or `--test-port`, currently supported for backward compatibility) to pick a different port. You can pass `0` to pick any available port (useful for testing multiple projects in parallel).
+
+```sh
+ember-test --port 0
+```
+
+</details>
+
+> [!NOTE]
+>
+> `ember-testem` provides a limited API on purpose.
+>
+> For `ember-cli` options like `--host`, `--launch`, `--reporter`, `--ssl`, `--ssl-cert`, `--ssl-key`, `--test-page`, `--testem-debug`), [configure `testem` in `testem.mjs` instead](https://github.com/ember-cli/ember-cli/blob/v7.3.0-ember-cli/lib/tasks/test.js#L54-L71).
 
 
 ## Compatibility

package/dist/bin/ember-test.js

@@ -7,12 +7,27 @@ import { run } from '../src/run.js';
 process.title = 'ember-test';
 // Set codemod options
 const argv = yargs(hideBin(process.argv))
+    .option('filter', {
+    alias: 'f',
+    describe: 'Specify a keyword for which modules and tests to run',
+    type: 'string',
+})
+    .option('module', {
+    alias: 'm',
+    describe: 'Specify the name of a module to run',
+    type: 'string',
+})
     .option('path', {
+    default: 'dist',
     describe: 'Relative path to the test build',
     type: 'string',
+})
+    .option('port', {
+    describe: 'Port for running tests. Pass 0 to automatically pick an available port.',
+    type: 'number',
 })
     .option('root', {
-    describe: 'Where to run the codemod',
+    describe: 'Project root',
     type: 'string',
 })
     .option('server', {
@@ -24,11 +39,16 @@ const argv = yargs(hideBin(process.argv))
     describe: 'Port for running tests. Pass 0 to automatically pick an available port.',
     type: 'number',
 })
+    .deprecateOption('test-port', 'Use --port instead.')
     .parseSync();
 const codemodOptions = {
-    buildPath: argv['path'] ?? 'dist',
+    buildPath: argv['path'],
+    filters: {
+        filter: argv['filter'],
+        module: argv['module'],
+    },
+    port: argv['test-port'] ?? argv['port'],
     projectRoot: argv['root'] ?? process.cwd(),
     server: argv['server'],
-    testPort: argv['test-port'],
 };
 void run(codemodOptions);

package/dist/src/steps/create-options.js

@@ -1,9 +1,10 @@
 export function createOptions(codemodOptions) {
-    const { buildPath, projectRoot, server, testPort } = codemodOptions;
+    const { buildPath, filters, port, projectRoot, server } = codemodOptions;
     return {
         buildPath,
+        filters,
         launchBrowser: Boolean(server),
+        port,
         projectRoot,
-        testPort,
     };
 }

package/dist/src/steps/run-tests/run-tests-in-ci.js

@@ -1,17 +1,19 @@
 import { join } from 'node:path';
 import Testem from 'testem';
+import { getQueryParams } from '../../utils/run-tests/get-query-params.js';
 export async function runTestsInCI(options) {
-    const { buildPath, projectRoot, testPort } = options;
+    const { buildPath, filters, port, projectRoot } = options;
     const testemInstance = new Testem();
     const startOptions = {
         launch: false,
-        port: testPort,
+        port,
     };
     testemInstance.setDefaultOptions({
         ...startOptions,
         config_dir: projectRoot,
         cwd: join(projectRoot, buildPath),
         parallel: 1,
+        query_params: getQueryParams(filters),
     });
     return new Promise((resolve, reject) => {
         testemInstance.startCI(startOptions, (exitCode, error) => {

package/dist/src/steps/run-tests/run-tests-in-dev.js

@@ -1,17 +1,19 @@
 import { join } from 'node:path';
 import { watch } from 'chokidar';
 import Testem from 'testem';
+import { getQueryParams } from '../../utils/run-tests/get-query-params.js';
 export async function runTestsInDev(options) {
-    const { buildPath, projectRoot, testPort } = options;
+    const { buildPath, filters, port, projectRoot } = options;
     const testemInstance = new Testem();
     const startOptions = {
         launch: false,
-        port: testPort,
+        port,
     };
     testemInstance.setDefaultOptions({
         ...startOptions,
         config_dir: projectRoot,
         cwd: join(projectRoot, buildPath),
+        query_params: getQueryParams(filters),
     });
     const watcher = watch([buildPath], {
         awaitWriteFinish: true,

package/dist/src/utils/run-tests/get-query-params.js

@@ -0,0 +1,10 @@
+export function getQueryParams(filters) {
+    const params = [];
+    if (filters.module) {
+        params.push(`module=${filters.module}`);
+    }
+    if (filters.filter) {
+        params.push(`filter=${filters.filter}`);
+    }
+    return params.join('&');
+}

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "ember-testem",
-  "version": "0.1.0",
-  "description": "",
+  "version": "0.3.0",
+  "description": "Backward- and forward-compatible testing for Ember projects",
   "keywords": [
-    "codemod",
-    "ember-codemod",
-    "emberjs"
+    "ci",
+    "ember",
+    "emberjs",
+    "testem",
+    "testing"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/ijlee2/ember-test.git"
+    "url": "https://github.com/ijlee2/ember-test.git",
+    "directory": "packages/ember-testem"
   },
   "license": "MIT",
   "author": "Isaac J. Lee",