Jasmine command

[flibbles]

This is the answer to issue #4194. It introduces the "--test" command for executing jasmine on command line rather than having it run automatically.

It does not change the behavior of browser-jasmine. I know we talked about making an event to run it, but here's the thing. Jasmine really doesn't want to be run more than once. And while I was able to get it so jasmine didn't run until you clicked a "<$button/>", it would always fall apart if you pressed the button twice. So for now, I'm only introducing the node.js side.

A few decisions I made.

• I made the command "--test", which might be too generic?
• It takes a second argument, which is a regular expression to specify specific tests or suites. This is the jasmine way of narrowing testing scope, not the Tiddlywiki way, which would be to use a filter. I can do either one (or both), but I implemented the jasmine testSpec filter because...
  1. It's how it works in the browser (Like when you click on failed tests, and it refreshes to run only that test.)
  2. You couldn't run individual tests using a Tiddlywiki filter. You could only specify which tiddlers run.
• Other than a lot of added documentation, there isn't currently a way to indicate to upgrading developers that they now need to add "--test" to their tiddlywiki.info files. I couldn't think of a way to do this that didn't introduce obnoxious problems.

If there are any ways you'd like me to do it differently, let me know. I'm happy to tweak whatever.

[Jermolene]

Thanks @flibbles

This is the answer to issue #4194. It introduces the "--test" command for executing jasmine on command line rather than having it run automatically.

I am concerned about backwards compatibility for users runnings the test suite their own CI. Perhaps we could automatically run the tests if the jasmine plugin is loaded but no commands have been specified? I appreciate that may not be straightforward as things stand.

It does not change the behavior of browser-jasmine. I know we talked about making an event to run it, but here's the thing. Jasmine really doesn't want to be run more than once. And while I was able to get it so jasmine didn't run until you clicked a "<$button/>", it would always fall apart if you pressed the button twice. So for now, I'm only introducing the node.js side.

That makes sense.

• I made the command "--test", which might be too generic?

That's a good point. For instance, I've considered adding support for end user wikitext tests (so that users can write tests for their own macros etc), and we might well want to use the --test command for such a thing.

Perhaps --runtest or --runjasmine?

• It takes a second argument, which is a regular expression to specify specific tests or suites. This is the jasmine way of narrowing testing scope, not the Tiddlywiki way, which would be to use a filter. I can do either one (or both), but I implemented the jasmine testSpec filter because...

A regexp makes sense here, I agree.

• Other than a lot of added documentation, there isn't currently a way to indicate to upgrading developers that they now need to add "--test" to their tiddlywiki.info files. I couldn't think of a way to do this that didn't introduce obnoxious problems.

Indeed, see my suggestion above.

One other thought is that it might be worth using the named arguments we introduced for the listen command to give us a bit of a backwards compatibility cushion.

[flibbles]

@pmario - Done. More documentation added.

@Jermolene - Done.

• I changed it from "--test" to "--jasmine". Seems succinct.
• The command takes a named parameter. (i.e. "--jasmine spec="^Framework")
• You suggested I have the tests run automatically if no commands are given. I did something different. Instead, if someone has jasmine installed, and they run TW on command line without running tests, they get a notice: Jasmine: no "--jasmine" command given, so skipping tests Here's why:
  1. Running tiddlywiki without commands vomits up the entire "usage" message, so I don't think anyone is doing this. Instead, anyone who runs tests regularly has probably created a build configuration rather than always running tiddlywiki.
  2. I think most people using jasmine just copied the "run tests and make test file" command set that you use in the "test" edition. (That's why I did.) Which means they would not benefit from automatically running tests unless they were designed to automatically run if the "--jasmine" command isn't called. And that would defeat the whole point of making it a command.
  3. Instead, a notice is printed. Yes, you'll see this notice whenever you use a jasmine-installed tiddlywiki project to do anything besides run tests, but it's just a single line. Maybe in five years, once everyone has had a chance to migrate, it can be removed.

[pmario]

I changed it from "--test" to "--jasmine". Seems succinct.

If we may change the testsuite in the future, the name may be different. I'd prefer --test use="jasmine" or something similar. ... IMO --test is more future proof

Also see: https://github.com/Jermolene/TiddlyWiki5/issues/6845 ... which would use an additional framework

[flibbles]

You raise some good points, @pmario.

@Jermolene, I can implement this any way we settle on, just let me know.

[flibbles]

Well, I've thought about it more. I would say either --test or --jasmine.

--test use=jasmine is tricky, because it implies multiple plugins all having testing frameworks, (like use=macro, or use=mocha). But the question is, if the --test command isn't part of the core, which plugin is introducing it? (And I don't think it should be part of core.)

--test is probably fine and what everyone would be familiar with. Other js testing frameworks use npm test mostly. Also, it seems unlikely that someone would have two javascript testing plugins installed at once. (Why have both jasmine and mocha?) And a testing framework for wikitext macros doesn't actually sound like something end-users would test on command-line.

Maybe I'm wrong. If we're still concern about collision, --jasmine would also work, because I'm guessing nearly every node.js developer will have a tiddlywiki.file build task called "test" which would run stuff like --jasmine --run-macro-tests --rendertiddler, so they'll be running tiddlywiki --build test anyway, regardless of what we pick.

[flibbles]

I've switched back to --test in expectation that we may settle on that, but that doesn't mean I'm hard set on --test. I'm totally open to discuss it more. It's easy to change again. I'm just trying to line this up for a merge.

[Jermolene]

Thanks @flibbles I am still concerned about the backwards compatibility impact of changing the way that the tests are run, but I accept that there isn't a good alternative at the moment. The message is a reasonable mitigation.

I've come around to using --test as the command name.

[flibbles]

That's understandable. The PR is here if/when you're ready.

I, for one, will be using this PR on my personal fork since I am long since tired of having all the tests run when I so much as run tiddlywiki --help.

[flibbles]

Resolved conflicts that emerged over time, and this is ready to merge again.

[Jermolene]

Thanks for your patience @flibbles