Naming the various modules

[Christian Johansen]

Hi,

I'm going over our various modules, looking for those that are stable enough to
slap "1.0" on. Before I do so I want to have a final round on naming. As the
number of modules have grown I suspect our current naming scheme is causing some
confusion, and I want input on how we can improve.

The Buster.JS modules can be roughly categorized in three main categories:

* Generally useful utilities
* Buster-specific modules relating to the test framework
* Buster-specific modules relating to automating browsers

Several modules fit in more than one of these categories, in which case,
"generally useful utilities" is usually the preferred category.

I think it would be easier for people to find their way around the codebase if
we used naming conventions to make the distinction between the different kinds
of modules. The following is a very rough suggestion, but I'm really only
throwing the idea out there - is it worthwile persuing? Gimme all you got.

Generally useful modules
-------------------------------------

My suggestion is that all non-Buster.JS specific modules earn their own names
without the "buster-" prefix. I already did this with "fs-watch-tree" and
"preferences" (which is a bit too generic a name I guess). There's a concern
here for modules that are used in browsers, see below.

buster-args - Command-line arguments parser
buster-assertions - Assertion functions
buster-bayeux-emitter - Wrap a bayeux client in an EventEmitter interface
buster-evented-logger - A logger object that emits events
buster-format - Pretty object formatting
buster-glob - Glob multiple patterns in one operation. This module will die.
                   Isaac said he'd welcome a patch that puts this ability into
                   node-glob, so I guess that's the right approach.
buster-stdio-logger - Builds on evented logger and allows you to redirect
                              messages in specific levels to one of two streams.
buster-terminal - ANSI escape sequences and string utilities
buster-user-agent-parser - Used to display human friendly browser names in the server.
fs-watch-tree - Watch file trees for changes recursively
preferences - Read preferences from a ~/.<project> file, environment variables and more.

Test-framework modules
-----------------------------------

I suggest the test framework modules keep the buster- names.

buster
buster-analyzer
buster-autotest
buster-core
buster-sinon
buster-static
buster-test
buster-util (not really intended for outside use)

Extensions
buster-amd
buster-html-doc
buster-jstestdriver
buster-lint
buster-syntax

Browser automation modules
------------------------------------------

The browser automation modules will become easily reusable starting with the
next beta, and even more so in 0.7/RC1. It feels like this part is a separate
sub-project, i.e. that maybe the automation modules should have a different
common prefix, like optimus-prime-capture-server etc. Obviously I'm not
suggesting they be called "optimus prime", but you get the point.

buster-capture-server
buster-cli
buster-configuration
buster-resources
buster-server-cli
buster-test-cli

A concern

One concern is that some of these modules are used in the browser. An explicit
goal for the Buster.JS test runner is to not pollute the global environment
where the tests run, so I really don't want too many global variables -
preferably only `buster`.

If e.g. buster-assertions moves to a non-buster prefixed name, it doesn't make
sense for it to use the `buster` global, does it? AMD is also not suitable,
because I don't want Buster to define a global `require` function. Suggestions
for how work around this? One, albeit slightly hacky, suggestion is to inject
things into `global.buster` if available, otherwise expose other globals. :|

Organization

I still think these modules should all be hosted under
http://github.com/busterjs/ - they are still part of the project. But I think
rethinking the naming strategy to make it clearer what kind of modules the
different modules are will help people getting around the code base.

What do you guys think?

Chris

[August Lilleaas]

I think one of the main goals should be separating Buster.JS, the product, from the components that Buster.JS is made of. This will make the separation between "the product buster" and "the reusable components in buster" clear as daylight.

For the reusable modules, I propose the following name: bt (for Buster Test). It's a boring name, but it doesn't have "buster" in it.

However, I'm not certain how to name the various modules. bt-capture-server makes sense, as it's completely reusable. bt-core, though? It's reusable, but not in a useful way by itself.. And what about the extensions? Are they specific to Buster, or can they be reused when people create their own testing framework by using Buster modules?

[Frédéric Merizen]

Hi,

I've been following busterjs for some time and I'm very impressed (I'm not using buster at work yet because of the windows issue, maybe I should join the effort).

I like the "clarify naming" strategy. I was roughly aware that there were general purpose modules and buster-specific modules, but explicit categories will make the code easier to understand for newcomers such as me.

On Fri, Jun 8, 2012 at 12:26 PM, Christian Johansen <chri...@cjohansen.no> wrote:

A concern

One concern is that some of these modules are used in the browser. An explicit
goal for the Buster.JS test runner is to not pollute the global environment
where the tests run, so I really don't want too many global variables -
preferably only `buster`.

If e.g. buster-assertions moves to a non-buster prefixed name, it doesn't make
sense for it to use the `buster` global, does it? AMD is also not suitable,
because I don't want Buster to define a global `require` function.

Maybe you shouldn't give up on AMD? With Almond ( https://github.com/jrburke/almond#readme ) you don't have to leak `require` into the global namespace.

 

--

Frederic Merizen
..........................................................
50, Avenue des Champs-Elysées
75008 Paris

(+33) 6 28 66 62 38

[Christian Johansen]

On Fri, Jun 8, 2012 at 1:02 PM, August Lilleaas <aug...@augustl.com> wrote:

I think one of the main goals should be separating Buster.JS, the product, from the components that Buster.JS is made of. This will make the separation between "the product buster" and "the reusable components in buster" clear as daylight.

I kinda disagree. My main goal is to separate Buster.JS, the test framework from the modules it's assembled from. There's a subtle semantic difference.
 

For the reusable modules, I propose the following name: bt (for Buster Test). It's a boring name, but it doesn't have "buster" in it.

Are you talking about buster-args et al? I think those should have proper names with no common prefix, to clarify the fact that they are stand-alone reusable modules that are not married to Buster.JS in any way.

Basically, my suggestion is that these:

buster
buster-analyzer
buster-autotest
buster-core
buster-sinon
buster-static
buster-test
buster-util

Keep their names as is. These:

buster-capture-server
buster-cli
buster-configuration
buster-resources
buster-server-cli
buster-test-cli

Should get a new common prefix. This way, the browser automation part becomes its own reusable sub-project that e.g. JS.Test can use. It needs name in its own right. If we opt for "Godzilla" (not an actual suggestion), we'd get:

godzilla-capture-server
godzilla-cli
godzilla-configuration
godzilla-resources
godzilla-server-cli
godzilla-test-cli

The rest of the modules should get proper unique names, like fs-watch-tree and preferences already have. All the modules will be hosted under the busterjs account and documented on busterjs.org of course, so that's what unites them under the same project.

Christian

[Christian Johansen]

Maybe you shouldn't give up on AMD? With Almond ( https://github.com/jrburke/almond#readme ) you don't have to leak `require` into the global namespace.

That is interesting. I'm not sure if we can use it, as we need to assemble stuff on the run, as I don't want to put built bundles in NPM. But we may be able to use this runtime. If so, we're rolling with this.

Christian

[August Lilleaas]

separate Buster.JS, the test framework from the modules it's assembled from

separating Buster.JS, the product, from the components that Buster.JS is made of

I think we mean the same thing: the product Buster.JS is a test framework. If not, can you elaborate?

Are you talking about buster-args et al? I think those should have proper names with no common prefix, to clarify the fact that they are stand-alone reusable modules that are not married to Buster.JS in any way.

I agree. That means finding new names for a bunch of things, but I guess it doesn't have to be clever. buster-capture-server can become browser-automation-capture-server or whatever.

the browser automation part becomes its own reusable sub-project that e.g. JS.Test can use. It needs name in its own right. If we opt for "Godzilla" (not an actual suggestion), we'd get:

That also makes sense. I don't think buster-capture-server belongs in the "godzilla" namespace, since it's completely not specific to tests and is completely reusable, but the other ones do.

[Christian Johansen]

I think we mean the same thing: the product Buster.JS is a test framework. If not, can you elaborate?

We're in agreement. 

 

the browser automation part becomes its own reusable sub-project that e.g. JS.Test can use. It needs name in its own right. If we opt for "Godzilla" (not an actual suggestion), we'd get:

That also makes sense. I don't think buster-capture-server belongs in the "godzilla" namespace, since it's completely not specific to tests and is completely reusable, but the other ones do.

No, they don't. We can group them as two things:

godzilla-capture-server
godzilla-resources
godzilla-server-cli (ready-to-use CLI to start/stop server, with pluggable templates for skinning etc)

I guess these could just stay within the buster- namespace. They will be reusable for other test frameworks too, but they are 1) test-framework-specific, and 2) modeled after buster's way of running tests.
buster-cli
buster-configuration
buster-test-cli

Christian

[Christian Johansen]

Alright, time to get concrete. My suggestion for a name for the browser automation tools is: Gepetto (as in, the guy who made Pinocchio). Here's all my suggestions (all names are free in NPM as of today). People, cast your votes!

buster-glob -> NOTHING. KILL.
I'd rather put in the time to make node-glob obsolete this package

buster-terminal -> string-colors + ansi-matrix
This module's strength lies in two things: 1) It only cares about strings, 2) you can instantiate it with { color: true|false, bright: true|false }, and if needed, it will be no-op.

I found several alternatives, but none that fit the above description.

This does look interesting: https://github.com/substack/node-charm It contains the implementation of what is called a "relativeGrid" in buster-terminal. We should probably use this module and scrap our own implementation.

I suggest we split this modules in the stateful colorizing object, and the matrix thing, which we use to draw dots "interactively" on the command line.

buster-user-agent-parser
Another problem that's been solved enough times already. I suggest we opt for platform.js (https://github.com/bestiejs/platform.js), which has results close to what we have today. Examples:

"Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; es-es) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16"

buster-user-agent-parser: {
    platform: "OS X",
    os: "OS X 10.5 (Leopard)",
    browser: "Safari",
    version: "5.0"
});

platform.js: {
    version: '5.0',
    name: 'Safari',
    os: 'Mac OS X 10.5.8',
    description: 'Safari 5.0 on Mac OS X 10.5.8',
    layout: 'WebKit',
    manufacturer: null,
    prerelease: null,
    product: null,
    ua: 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; es-es) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16'
}

The only that sucks is that they don't have the generic OS, like "OS X", which we use to generate class names so we can display the right logo. But I guess we can have a small "OS parser"?

buster-args -> argv-parse (just learned today that 'argv' stands for 'argument vector')
There are already tons of parsers in NPM. None of the ones I looked at provide the same functionality. I find that buster-args strongest feature is the way it "properly" implements many ways of passing options and arguments ("properly" = mirrored after lots of classic UNIX tools), and how it does nothing but parse args.

buster-assertions -> reas
Not the greatest name ever - refute assert - and it reads like "Reese".

buster-format -> stringify
There's another project called "stringy" which has one commit and the following readme: "Stringy.js will stringify your circular JS objects without complaint. Unfortunately it currently fails if the object hierarchy exceeds 30 total items."

buster-bayeux-emitter -> bayeux-emitter
buster-evented-logger -> evented-logger
buster-stdio-logger -> stream-logger
buster-capture-server -> gepetto-capture-server
buster-resources -> gepetto-resources
buster-server-cli -> gepetto-server-cli
fs-watch-tree -> Stays the same
preferences -> Stays the same

buster -> Stays the same
buster-analyzer -> Stays the same
buster-autotest -> Stays the same
buster-core -> Stays the same
buster-sinon -> Stays the same
buster-static -> Stays the same
buster-test -> Stays the same
buster-util -> Stays the same
buster-amd -> Stays the same
buster-html-doc -> Stays the same
buster-jstestdriver -> Stays the same
buster-lint -> Stays the same
buster-syntax -> Stays the same
buster-cli -> Stays the same
buster-configuration -> Stays the same
buster-test-cli -> Stays the same

Christian

[August Lilleaas]

The only that sucks is that they don't have the generic OS, like "OS X", which we use to generate class names so we can display the right logo. But I guess we can have a small "OS parser"?

Or contribute it to that project :) Sounds like a small semver compat addition.

buster-args -> argv-parse (just learned today that 'argv' stands for 'argument vector')
There are already tons of parsers in NPM. None of the ones I looked at provide the same functionality. I find that buster-args strongest feature is the way it "properly" implements many ways of passing options and arguments ("properly" = mirrored after lots of classic UNIX tools), and how it does nothing but parse args.

We're indeed POSIX spec compliant. Plus, the API doesn't control the flow (typically, argv parsers are big procedural objects), and we don't govern how the output looks (no STDIO at all).

I suggest posix-argv-parser.

buster-assertions -> reas
Not the greatest name ever - refute assert - and it reads like "Reese".

I propose refute-assert, less clever.

buster-format -> stringify
There's another project called "stringy" which has one commit and the following readme: "Stringy.js will stringify your circular JS objects without complaint. Unfortunately it currently fails if the object hierarchy exceeds 30 total items."

I think the name should contain more about what it does, specifically what it does that the built in Node.js sys.inspect doesn't.

buster-bayeux-emitter -> bayeux-emitter

Not a very big fan of this module name.. Like stringify I think it should say more about the purpose. Perhaps.. Dno.

Is it really reusable to anyone? And is it used more than one place? Perhaps it can be embedded into another module?

gepetto

Explain :D

[Christian Johansen]

On Sun, Jun 10, 2012 at 1:11 AM, August Lilleaas <aug...@augustl.com> wrote:

The only that sucks is that they don't have the generic OS, like "OS X", which we use to generate class names so we can display the right logo. But I guess we can have a small "OS parser"?

Or contribute it to that project :) Sounds like a small semver compat addition.

Of course.... :)
 

I suggest posix-argv-parser.

+1
 

buster-assertions -> reas
Not the greatest name ever - refute assert - and it reads like "Reese".

I propose refute-assert, less clever.

But also very awkward. I want a slightly more catchy name. Will think more about (and I'm open to more suggestions).
 

buster-format -> stringify
There's another project called "stringy" which has one commit and the following readme: "Stringy.js will stringify your circular JS objects without complaint. Unfortunately it currently fails if the object hierarchy exceeds 30 total items."

I think the name should contain more about what it does, specifically what it does that the built in Node.js sys.inspect doesn't.

It stringifies shit :) What about "stringspect"? :)
 

buster-bayeux-emitter -> bayeux-emitter

Not a very big fan of this module name.. Like stringify I think it should say more about the purpose. Perhaps.. Dno.

Is it really reusable to anyone? And is it used more than one place? Perhaps it can be embedded into another module?

Not really, I guess. In fact, searching around it seems like it's only used in buster-client, which is going away anyway. Which is actually kinda strange. Does the new client allow me to send any kind of event over the wire?
 

gepetto

Explain :D

He's the guy who made Pinocchio. Was mostly thinking of someone controlling the strings - the puppet master :) http://clipdenoticias.com/images/gepetto-i1.jpg

Stein Magnus also suggested we rename "preferences" to "prefsink" -> multiple preference sources, one sink to find them in. I like it.

Christian
 

[Christian Johansen]

Ok, so it seems buster-bayeux-emitter will also be deprecated. To summarize what we have so far, here's the list. 5 names are pending so far.

buster-terminal -> string-colors, ansi-matrix (also, use charm for the grid)
buster-user-agent-parser -> deprecate, use platform.js
buster-args -> posix-argv-parser
buster-assertions -> ??? Feedback wanted
buster-format -> ??? Feedback wanted. Suggestion: stringspect

buster-evented-logger -> evented-logger
buster-stdio-logger -> stream-logger

buster-capture-server -> gepetto-capture-server (???)
buster-resources -> gepetto-resources (???)
buster-server-cli -> gepetto-server-cli (???)
preferences -> prefsink
fs-watch-tree

buster
buster-analyzer
buster-autotest
buster-core
buster-sinon
buster-static
buster-test
buster-util

buster-amd
buster-html-doc
buster-jstestdriver
buster-lint
buster-syntax

buster-cli
buster-configuration
buster-test-cli
buster-glob -> deprecate
buster-bayeux-emitter -> deprecate

Christian

[Christian Johansen]

Sorry for the noise. Just performed a couple renames. Here's the current status:

Needs feedback
buster-assertions -> ???
buster-format -> stringspect

buster-capture-server -> gepetto-capture-server
buster-resources -> gepetto-resources
buster-server-cli -> gepetto-server-cli

Todo: Change names

buster-evented-logger -> evented-logger
buster-stdio-logger -> stream-logger

Todo: Extract as new modules
deepEqual / match (from assertions) -> compare module
isElement (from buster-core) -> will remove a few dependencies to buster-core, which is a very random collection of things
string-colors (from buster-terminal)
ansi-matrix (from buster-terminal, requires integration with charm and ditching our own relativeGrid)

Alphabetic list of projects with finalized names
buster
buster-amd
buster-analyzer
buster-autotest
buster-cli
buster-configuration
buster-core
buster-html-doc
buster-jstestdriver
buster-lint
buster-sinon
buster-static
buster-syntax
buster-test
buster-test-cli
buster-util
fs-watch-tree
posix-argv-parser
prefsink

Deprecate (eventually)
buster-bayeux-emitter
buster-client
buster-glob
buster-user-agent-parser

Christian

[Christian Johansen]

Final list of names. If you're very unhappy with any of these, now is the time to let us know.

Todo: Change names

buster-assertions -> tush
buster-format -> stringspect

buster-capture-server -> ramp
buster-resources -> ramp-resources

buster-evented-logger -> evented-logger
buster-stdio-logger -> stream-logger

Todo: Extract as new modules
deepEqual / match (from assertions) -> compare module
isElement (from buster-core) -> will remove a few dependencies to buster-core, which is a very random collection of things
string-colors (from buster-terminal)
ansi-matrix (from buster-terminal, requires integration with charm and ditching our own relativeGrid)

Alphabetic list of projects with finalized names
buster
buster-amd
buster-analyzer
buster-autotest
buster-cli
buster-configuration
buster-core
buster-html-doc
buster-jstestdriver
buster-lint
buster-sinon
buster-static
buster-syntax

buster-server-cli

[Magnar Sveen]

I'd like to back Jodals' suggestion "reassure" for buster-assertions. :-)

- Magnar

[Christian Johansen]

I like both jodal's "reassure" and your (Magnar) "referee". In fact referee is my current favorite, it's short, memorable, "a guy" (something one could personalize), has a fitting analogy, and gives us this epic API: referee.addAssertion(...)

C