# @test-ui/core

> A utility that facilitates controlling a remote software test suite

Latest version **1.3.3** (published 2018-11-08) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install @test-ui/core
pnpm add @test-ui/core
yarn add @test-ui/core
bun add @test-ui/core
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.3.3 |
| Published | 2018-11-08 |
| First published | 2018-07-29 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 558 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Mike North |
| Maintainers | mike-north-bot, northm |
| Keywords | ember-addon |

## Links

- npm: https://www.npmjs.com/package/@test-ui/core
- Repository: https://github.com/mike-north/test-ui-core
- Homepage: https://github.com/mike-north/test-ui-core#readme
- Issues: https://github.com/mike-north/test-ui-core/issues
- npm.io page: https://npm.io/package/@test-ui/core

## Dependencies (7)

- [penpal](https://npm.io/package/penpal.md) ^3.0.3
- [youarei](https://npm.io/package/youarei.md) ^1.0.3
- [bite-log](https://npm.io/package/bite-log.md) ^1.6.0
- [json-typescript](https://npm.io/package/json-typescript.md) ^1.0.1
- [micro-observable](https://npm.io/package/micro-observable.md) ^1.1.4
- [object-predicate](https://npm.io/package/object-predicate.md) ^1.0.4
- [@mike-north/types](https://npm.io/package/@mike-north/types.md) ^1.0.0

## Recent versions

- 1.3.3 (latest) — 2018-11-08
- 1.3.2 — 2018-11-04
- 1.3.1 — 2018-08-11
- 1.3.0 — 2018-08-11
- 1.2.7 — 2018-08-08
- 1.2.6 — 2018-08-08
- 1.2.5 — 2018-08-08
- 1.2.4 — 2018-08-08
- 1.2.3 — 2018-08-08
- 1.2.2 — 2018-08-08
- 1.2.1 — 2018-08-08
- 1.2.0 — 2018-08-07
- 1.1.2 — 2018-08-07
- 1.1.1 — 2018-08-07
- 1.1.0 — 2018-08-07
- … 20 more at https://npm.io/package/@test-ui/core/versions

## README

# @test-ui/core

[![Build Status](https://travis-ci.org/mike-north/test-ui-core.svg?branch=master)](https://travis-ci.org/mike-north/test-ui-core)
[![Version](https://img.shields.io/npm/v/@test-ui/core.svg)](https://www.npmjs.com/package/@test-ui/core)

A utility that facilitates controlling a remote software test suite (i.e., running QUnit or Mocha tests in an `<iframe>`).

## Setup

```sh
npm install --save-dev @test-ui/core
```

## Use

This library involves setting up a client and a server, each with a respective "connection" that handles the particulars of communication. Support for `postMessage` as a communication channel is built-in, but it's possible to implement support for other technologies (i.e., WebSockets, XHR, etc...)

### The Server

First, you must extend the abstract `Server` class, and implement all abstract methods. 

```ts
import { Server } from '@test-ui/core'

class MyServer extends Server {

  /**
   * Handle the particulars of setting up the test server's connection.
   * Optionally, a unique "session id" may be returned. If the server
   * has to restart for one reason or another, this id may be used
   * to retrieve some state from the `Client`.
   */
  protected async boot(): Promise<{ id: string } | undefined> {
    
    // Somewhere, sometime, notify the client that the server booted
    (await this.conn).notifyIsBooted(stateRef);
  }

  /**
   * Handle the particulars of preparing the test environment in preparation
   * for a test run. This might include setting filters/options as appropriate
   * 
   * The return value's promise resolves to an object with a `ready` property.
   * If this has a `true` value, the test run will proceed. If `false` it
   * will not.
   * 
   * @param state a simple object containing an id, and options for the test run
   */
  protected async prepareEnvironment(state: State): Promise<{ ready: boolean }> {

    // Somewhere, sometime, notify the client that the server is prepared
    (await this.conn).notifyIsPrepared(state);
  }

  /**
   * Run the tests, as described by the optional filter
   * 
   * @param moduleFilter Filter describing test modules that should be run
   */
  protected async runTests(moduleFilter?: PredicateObject<TestModule>): 
  Promise<void> {

    // Emit send test results back to the client
    this.sendTestData(...)
  }

}
```

Before we instantiate the server, we need a connection. You can either create your own connection type or use the built-in `IFrameConnectionServer` type.

```ts
import MyServer from './my-server';
import { IFrameConnectionServer } from '@test-ui/core';

const myServer = new MyServer({
  connection: new IFrameConnectionServer();
});

myServer.start(); // start the server
```


### The Client

You must create a subclass of the `Client` type
```ts
import { Client } from '@test-ui/core';

class MyClient extends Client {

  /**
   * Handle anything specific that must be done on the client, before we
   * instruct the server to get ready for a test run
   */
  protected async prepareServerFrame(moduleFilter?: PredicateObject<TestModule>): Promise<any> {}
}

```

In order to instantate the client, you'll need to pass it a connection. You can either create your own connection class, or use the built-in `IFrameConnectionClient` type.

```ts
const frame: HTMLIFrameElement = document.querySelector('iframe');
const client = new MyClient({
  connection: new IFrameConnectionClient({
    frame,
    baseUrl: '/tests' // URL of the iframe src
  })
});
```

## Copyright

(c) 2018 LinkedIn

---
_Source: https://npm.io/package/@test-ui/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._