ember-testem 0.1.0 → 0.2.0

package/README.md

@@ -3,6 +3,238 @@
 _Forward- and backward-compatible testing for Ember projects_
 
 
+## Quickstart
+
+1\. Install `ember-testem` as a development dependency.
+
+```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"
+  },
+  "devDependencies": {
++     "ember-testem": "..."
+  }
+}
+```
+
+<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,
+    }),
+  ],
+});
+```
+
+</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 type { UserConfig } from 'vite';
+
+import baseConfiguration from './vite.config.mts';
+
+export default {
+  ...baseConfiguration,
+  build: {
+    minify: false,
+    sourcemap: true,
+  },
+} satisfies UserConfig;
+```
+
+</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 `--test-port` to pick a different port. You can pass `0` to pick any available port (useful for testing multiple projects in parallel).
+
+```sh
+ember-test --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
 
 - Node.js v22 or above

package/dist/bin/ember-test.js

@@ -7,6 +7,16 @@ 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', {
     describe: 'Relative path to the test build',
     type: 'string',
@@ -27,6 +37,10 @@ const argv = yargs(hideBin(process.argv))
     .parseSync();
 const codemodOptions = {
     buildPath: argv['path'] ?? 'dist',
+    filters: {
+        filter: argv['filter'],
+        module: argv['module'],
+    },
     projectRoot: argv['root'] ?? process.cwd(),
     server: argv['server'],
     testPort: argv['test-port'],

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

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

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

@@ -1,7 +1,8 @@
 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, projectRoot, testPort } = options;
     const testemInstance = new Testem();
     const startOptions = {
         launch: false,
@@ -12,6 +13,7 @@ export async function runTestsInCI(options) {
         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,8 +1,9 @@
 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, projectRoot, testPort } = options;
     const testemInstance = new Testem();
     const startOptions = {
         launch: false,
@@ -12,6 +13,7 @@ export async function runTestsInDev(options) {
         ...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.2.0",
+  "description": "Forward- and backward-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",