@ebay/marko-playground

marko-playground

This project is a development utility for Marko UI components. On launch, it automatically detects all components in your Marko application and allows you to browse through them, rendering all declared use cases or states. Scenarios can be written in fixtures that represent the backend responses or props from the parent component. As a result, component development becomes way faster, regression testing easier and visual defects can be spotted early.

Getting started

First, add marko-playground to your project by running the following command:

yarn add --dev marko-playground
#or
npm i --save-dev marko-playground

Now you can start the playground via

yarn marko-playground
#or
npm run marko-playground

Declaring states

When marko-playground detects a UI component, it reads its states from the directory <component>/test/fixtures. If no state (or fixture) has been found, it falls back to an empty state and renders the component accordingly.

Additional states can be defined with the following directory structure (which is also used by marko-tester):

<component>/test/
            ⤷ fixtures/
               ⤷ default.json
               ⤷ another-use-case.json

Example of default.json

{
    "viewModel": {
        "title": "default title"
    }
}

Configuration

The marko-playground tool can be configured by adding a test/playground/config.json to your project. If no file is found, the following default configuration is used instead:

{
  // Playground will listen on this port, override it with environment variable PORT:
  "port": 8080,

  // Widget components will be searched starting from this directory,
  // override with COMPONENTS_ROOT_DIR
  "componentsRootDir": "./src/components",

  // Widget playground's template will be searched in this directory relative 
  // to component's directory, override with PLAYGROUND_DIR:
  "playgroundDir": "test/playground",

  // Lasso config, override with LASSO_CONFIG indicating local lasso config JSON file:
  "lasso": {
    "plugins": [
      "lasso-less",
      "lasso-marko"
    ],
    "outputDir": "static",
    "bundlingEnabled": false,
    "minify": false,
    "fingerprintsEnabled": false
  }
}

Lasso flags support

You can pass flags to lasso page by setting environment variable FLAGS, for example: FLAGS=skin-ds6,mobile

Custom playgrounds

If you don't like the standard component template used in playground, you can use your own. Simply put it in you component's test/playground directory and name it index.marko or template.marko. You can always change the location of the template by changing the config property playgroundDir or environment variable PLAYGROUND_DIR. Example

Components discovery

The UI component detection is based on Marko's configuration and respect's the configuration's tags-dir and <component>/renderer property.

Usually, you have a marko.json in your project (or rely on the defaults which is the components directory). The marko file looks like this:

{
    "tags-dir": "./components"
}

If you have a separate component project, your marko.json should look similar to this:

{
    "<component-name>": {
        "renderer": "./component-dir"
    }
}

That file usually resides in the root directory (marko documentation.)

Debugging

For more diagnostic messages set environment variable DEBUG to truthy value like DEBUG=1.

Development

Git clone this repo, then install everything:

yarn 
#or 
npm install

Then start playground with test components:

yarn start
#or
npm start

Tests can be executed via:

yarn test
#or
npm test

CI

https://travis-ci.org/eBay/marko-playground

Licence

Copyright 2018 eBay Inc. Developer(s): Timur Manyanov

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.