phtml-tape v4.1.0

pHTML Tape

pHTML Tape lets you quickly test pHTML plugins.

1. Install this dependency to your project:

   npm install phtml-tape --save-dev

2. Add the phtml-tape task to your package.json:

   {
      "scripts": {
        "test": "phtml-tape"
      }
   }

3. Add tests to your .tape.js file:

   module.exports = {
     'basic': {
       message: 'supports basic usage'
     }
   };

That’s it! Empty tests will be auto-generated.

npm test

Options

Options may be passed through package.json using phtmlConfig:

{
  "phtmlConfig": {
    "plugin": "path/to/plugin.js",
    "config": "path/to/.tape.js",
    "fixtures": "path/to/htmldir"
  }
}

Options may be passed through arguments:

phtml-tape --plugin=path/to/plugin.js --config=path/to/.tape.js

Test Options

message

The message provided to the console to identify the test being run.

{
  'some-test': {
    message: 'supports some test usage'
  }
}

options

The options passed into the pHTML plugin for the test.

{
  'some-test': {
    options: {
      someOption: true,
      anotherOption: 5,
      etc: 'etc'
    }
  }
}

processOptions

The process options passed into pHTML for the test. Read the pHTML documentation for more details.

{
  'some-test': {
    processOptions: {
      map: {
        inline: true,
        sourcesContent: true
      }
    }
  }
}

warnings

Either the number of warnings expected to be generated by the test, or an object used to match warnings given by the test.

{
  'some-test': {
    warnings: 3
  }
}

{
  'some-test': {
    warnings: {
      text: /should warn/
    }
  }
}

error

An object used to match errors thrown by the test.

{
  'some-test': {
    errors: {
      message: 'You should not have done that'
    }
  }
}

In that example, the error expects a field of message to be the string You should not have done that. In order that errors can be inspecific, regular expressions may also be used, so that something like message: /^You should not have done/ would also match You should not have done this.

source

The location of the source HTML file, relative to the fixtures directory. This file is passed through the pHTML plugin.

{
  'some-test': {
    source: 'alterate-source.html'
  }
}

In that example, a some-test field would automatically populate the source as some-test.html unless it was overridden. In order that multiple tests may use the same source file, a some-test:modifier field would still populate the source as some-test.html.

expect

The location of the expected HTML file, relative to the fixtures directory. This file is represents the expected HTML result of source after being passed through the pHTML plugin.

{
  'some-test': {
    expect: 'alterate-expect.html'
  }
}

In that example, a some-test field would automatically populate the expect as some-test.expect.html unless it was overridden. In order that multiple tests may use the same source file, a some-test:modifier field would still populate the source as some-test.html, but alter the expect to be some-test.modifier.expect.html.

result

The location of the resulting HTML file, relative to the fixtures directory. This file is the HTML result of source after being passed through the pHTML plugin.

{
  'some-test': {
    result: 'alterate-result.html'
  }
}

In that example, a some-test field would automatically populate the result as some-test.result.html unless it was overridden. In order that multiple tests may use the same source file, a some-test:modifier field would still populate the source as some-test.html, but alter the result to be some-test.modifier.result.html.

before

A function to be run before the particular test. This is helpful for generating variables, content, or files that will be used by the plugin.

{
  'some-test': {
    before: () => {
      /* do something before the plugin runs */
    }
  }
}

after

A function to be run after the particular test. This is helpful for cleaning up variables, content, or files that were used by the plugin.

{
  'some-test': {
    after: () => {
      /* do something after the plugin runs */
    }
  }
}

plugin

A plugin or array of plugins that will specifying alternative plugin

{
  'some-test': {
    plugin: () => require('phtml')(
      require('some-plugin-that-runs-before'),
      require('.'),
      require('some-plugin-that-runs-after')
    )
  }
}

CLI Options

Options can be passed into the phtml-tape function or defined in package.json using the phtmlConfig property.

plugin

The path to the plugin being tested.

phtml-tape --plugin=path/to/plugin.js

{
  "phtmlConfig": {
    "plugin": "path/to/plugin.js"
  }
}

By default, plugin is the resolved file from the current working directory.

config

The path to the configuration file used to run tests.

phtml-tape --config=path/to/config.js

{
  "phtmlConfig": {
    "config": "path/to/config.js"
  }
}

By default, pHTML Tape will try to use the file defined by config, or the config directory’s phtml-tape.config.js or .tape.js file. By default, config is the current working directory.

fixtures

The path to the fixtures used by tests.

phtml-tape --fixtures=path/to/tests

{
  "phtmlConfig": {
    "fixtures": "path/to/tests"
  }
}