# Keyman Engine for Web
The Original Code is (C) SIL International

## Prerequisites
See [build configuration](../docs/build/index.md) for details on how to configure your build environment.

**********************************************************************

The following folders contain the distribution for KeymanWeb:

    source                       Source code
    source/resources/osk         OSK resources for inclusion in mobile app builds;
                                 keymanweb-osk.ttf is maintained at https://github.com/silnrsi/font-keymanweb-osk
    unit_tests                   Automated testing resources

    intermediate                 Intermediate compiled code; TypeScript source is compiled here before it is minified.
    release/web                  Fully-compiled KeymanWeb modules for testing
    release/embedded             Fully-compiled KMEA/KMEI modules for inclusion in mobile app builds
    release/unminified/web       Fully-compiled but non-minified KeymanWeb modules
    release/unminified/embedded  Fully-compiled KMEA/KMEI modules for inclusion in mobile app builds

    samples                      Sample pages demonstrating ways to link with KeymanWeb
    testing                      Test-case web-pages for various aspects of KeymanWeb functionality
    unit_tests                   A Node-driven test suite for automated testing of KeymanWeb

## Usage
Open **index.html** or **samples/index.html** in your browser. Be sure to compile KeymanWeb before viewing the pages.

Refer to the samples for usage details.

To view pages using compiled KeymanWeb,
1. cd to **keyman/web/source**
2. Run `./build.sh`

### `build.sh` options:

*  `-ui`
    - to compile desktop user interface modules to output folder
*  `-test`
    - to compile for testing without copying resources or updating the saved version number.
*  `-embed`
    - to compile only the KMEA/KMEI embedded engine.
*  `-web`
    - to compile only the KeymanWeb engine.
*  `-debug_embedded`
    - to compile a readable version of the embedded KMEA/KMEI code
*  `-no_minify`
    - to disable the minified '/release/web' and '/release/embedded' build sections.
    - the '/release/unminified/web' and '/release/unminified/embedded' folders will still be built.
*  `-clean`
    - to erase pre-existing build products before the build.

If more than one target is specified, the last one will take precedence.

### Unit Testing ###

Before running unit tests on KeymanWeb, first run `./build.sh` according to the instructions above.

Once the build is complete, running `npm test` will run the unit testing suite on your local machine in-browser.
Alternatively, see `unit_tests/test.sh`, which the former command executes.

### Debugging Unit Tests
1. During development, to run a specific unit test, change the `it` to `it.only`.
    You can also run all tests under a specific group with `describe.only`.
2. From this directory, run `./unit_tests/test.sh -debug`.
Alternatively, from `web/` or any `web/` subdirectory,
    ```
    npm run test -- -debug
    ```
    The `--` part tells `npm` to funnel anything to the script as the script's command-line parameters.
    As long as it's run from somewhere within the `web/` folder's hierarchy, that line will always run from `web/`,
    as that's where `package.json` is.

3. When the browser halts, click the "Debug" button which opens a new debugging tab.
4. In the Dev console, you can set a breakpoint in your test and refresh the page to debug