kevgo / text-runner Goto Github PK
View Code? Open in Web Editor NEWTest-Runner for Text
Test-Runner for Text
tut-run docs/*.md
As a tutorial writer
I want the tests for my tutorial to run in a separate directory from my tutorial
So that I don't clutter up my tutorial source code with temporary files creating by running it.
and see if that feels better than anchor tags
Feature: running a single MarkDown file
As a tutorial writer
I want to be able to test a single MarkDown file
So that I can check my current changes quickly without having to run the entire test suite.
- run `tut-run run [<file path>]` or `tut-run [<file path>]` to test only the given file
Background:
Given I am working on the "multiple-files" example
Scenario: testing a single file via "tut-run run"
When running "tut-run run 2.md"
Then it runs only the tests in "2.md"
Scenario: testing a single file via "tut-run"
When running "tut-run 2.md"
Then it runs only the tests in "2.md"
Scenario: testing a non-existing file
When trying to run "tut-run zonk.md"
Then it aborts with the error "File not found: zonk.md"
As a non-technical user
I want to be able to download a binary file for Tutorial Runner
So that I can simply use it without having to install and configure Node.JS first.
use YARN on CI
If they don't take a callback parameter, don't wait for them.
Use Tertestrial to check the Tertestrial readme
tut-run should empty the tmp directory before running to make sure it only tests things in the actual markup
As a Node.JS library writer
I want to be able to use Tutorial Runner programmatically via its JS API
So that I can fully embed it into my own test suites and control it easily.
With embedded screenshots against which it diffs
It doesn't seem to be there
As a developer writing a tutorial for a software tool or library I have built
I want to be able to implement actions in the language my tool is written in
So that my actions can call my library programmatically similar to how a developer would
And I can code custom actions in the programming language I am familiar with.
Notes:
Communication Protocol:
Example:
wire format communication during testing of a library that exposes a "hello" method that users can call:
{
"command": "runAction",
"name": "callHello",
"argument": "world"
}
{
"event": "action.start",
"activity": "calling 'hello' with 'world'"
}
action runner calls "hello" with parameter "world"
action runner sends:
{
"event": "action.success"
}
Or figure out how to test against multiple Node versions
for example https://github.com/wooorm/remark-lint
Feature: check the minimum supported Node version
As the author of an NPM module
I want to be able to specify the supported NodeJS versions
So that my users know how to install this just from reading the documentation.
- wrap the supported Node version(s) into a "minimumSupportedNodeVersion" action in your documentation
- the action looks into .travis.yml and makes sure the listed versions show up there
- the action warns about versions in .travis.yml that are not listed in the document
Scenario: providing a matching version
Given my workspace contains a file 1.md with the content:
"""
Requires Node version <a class="tutorialRunner_minimumSupportedNodeVersion">4</a> or above
"""
And my workspace contains a file .travis.yml with the content:
"""
node:
- 3
- 4
- 5
"""
When running tut-run
Then it signals:
|....
When building a text suite
I want that missing actions are scaffolded for me on demand
So that I don't waste time copy-and-pasting boilerplate code.
Feature: testing all docs in a subfolder
As a tutorial writer working on a large collection of documentation
I want to be able to test only the documents in a particular folder
So that I get my test result quickly without having to test everything.
- run "tut-run [folder-to-test]" to test all docs in the given folder
Scenario: testing files in a subfolder
They are too complicated right now
Right now the readme mentions the globals
key for all commands, but it really only applies to runConsole
actions.
In order to use custom steps:
right now it only tests files right in that directory
Feature: setting the formatter via the command line
As a tutorial writer
I want to be able to set the formatter via a command-line parameter
So that I can play with different formatters without having to update tut-run.yml.
- provide the formatter to use via the "--formatter=<FORMATTER NAME>" parameter
- command-line parameters override the configured values
Background:
Given my workspace contains a tutorial
Scenario: using the iconic formatter via the command line
When running "tut-run --formatter iconic"
Then I see "[check]"
Scenario: providing an unknown formatter via the command line
When trying to run "tut-run --formatter zonk"
Then the test fails
And I see "unknown formatter: zonk"
Feature: action libraries
As a Tutorial Author documenting a variety of projects
I want to be able to share custom actions between projects
So that I don't have to implement them redundantly in every project.
- actions can be put into dedicated source code repos
- to use external custom actions,
list the address of the repo that contains them in tutorial.yml
- the address can point to a branch of the repo (when debugging shared steps)
- Tutorial Runner clones/updates that repo on start
and uses the custom actions when running
TutorialRunner should verify that all links outside of actionable blocks point to useful URLs.
Only print warnings if they don't since external sites could be down.
With embedded screenshots against which it diffs
Optional separate implementation of the API and CLI version of scenarios.
Example:
Feature: running a single MarkDown file
Scenario:
Given I am in a directory that contains the "multiple-files" example
When running Tutorial Runner with only the file 1.md
Then it runs only the tests in 1.md
This scenario doesn't tell the reader much, because all the interesting parts are buried in the step definitions. It's nice to know that I can run it with only one file, but how exactly am I doing this via the CLI or API?
Feature: running a single MarkDown file
Background:
Given I am in a directory that contains the "multiple-files" example
@clionly
Scenario Outline: testing a single file via the CLI
When running "tut-run 1.md"
Then it runs only the tests in "1.md"
@clionly
Scenario: testing a non-existing file via the CLI
When trying to run "tut-run zonk.md"
Then the test fails with:
| ERROR MESSAGE | unknown command: zonk.md |
| EXIT CODE | 1 |
@apionly
Scenario Outline: testing a single file via the API
When executing "tutorialRunner.execute 'run', '1.md', <callback>"
Then it runs only the tests in "1.md"
Scenario: testing a non-existing file via the API
When executing "tutorialRunner.execute 'run', 'zonk.md', <callback>"
Then it returns the error "unknown command: zonk.md"
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.