Documentation for the new common test task. interested in comments on direction.

[Eric Merritt]

ct Task
=======

The ct task is a method of running the [Common Test
Framework](http://www.erlang.org/doc/apps/common_test/users_guide.html) on a the
project. You should be familiar with the common test framework to use this task.

Configuration
-------------

In this case Sinan does not do *any* configuration for you outside of
setting up the proper code paths. Sinan does however give you several variables
that you can use in your options (at least those options that contain directory
specifications).

These exist to help you configure your tests. It is suggested that you put all
output under the 'build_dir' and no in your project itself. Otherwise sinan
clean will be *unable* to clean the project correctly. However, this is
completely up to you.

### Available Variables

These are the variables available in your configuration options.

*Project Dir*

This is the project directory. This should be the same as CWD, since Sinan sets
the projec directory to be the current directory.

$project_dir$

*Build Root*

The build root points to the top level of the build directory. This usually
points `$project_dir$/_build`. You shouldn't put too much at this
level directory,
because you can have multiple releases that may step on each other.

$build_root$

*Build Dir*

Build dir points to the build output directory, that is the release directory
where all build output ends up.

$build_dir$

*Release*

This is simply the name of the currently active release.

$release$

*Release Version*

This is the currently set version of the *release*.

$release_vsn$

*Apps Dir*

This points to the 'lib' dir of the release directory. This is equivalent to
`$apps_dir$/lib`.

$apps_dir$

*Release Dir*

This points to the directory containing the release metadata. It is equivalent
to `$build_dir$/releases/$release_vsn$`

$release_dir$

*Home Dir*

This is simply the user's home directory.

$home_dir$

*Application Directory*

Lets say we had an application called foo. The variable `$foo_dir$` would point
to the root directory of that application. So in this model the ebin directory
of foo would look like '$foo_dir$/ebin'.

$<app_name>_dir$

*Application Version*

The is similar to `$<app_name>_dir$` except contains the version of the
application instead of its dir. So for our foo example if we wanted the version
of foo we would do `$foo_vsn$`.

### Multiple Common Test Configurations

Sinan give you the ability to have multiple common test configurations. The
configurations are are specified as follows.

{ct_config, [{config_name(), terms()}]}.

Lets say we had a configuration call alternate in our bar release. We might
configure it as follows.

{ct_config, [{alternate, [{dir, \"$foo_dir$/test\"}]}]}.


To run that configuration you would simple call this from the command line

$> sinan ct alternate

### Available Configuration Options

These are exactly the same options taken by
[ct:run/1](http://www.erlang.org/doc/man/ct.html#run-1). Look there for the
common test documentation.

{dir, TestDirs} % Variables Supported
{suite, Suites}
{group, Groups}
{testcase, Cases}
{spec, TestSpecs}
{label, Label}
{config, CfgFiles} % Variables Supported
{userconfig, UserConfig} % Variables Supported
{allow_user_terms, Bool}
{logdir, LogDir} % Variables Supported
{silent_connections, Conns}
{stylesheet, CSSFile} % Variables Supported
{cover, CoverSpecFile} % Variables Supported
{step, StepOpts}
{event_handler, EventHandlers}
{include, InclDirs} % Variables Supported
{auto_compile, Bool}
{create_priv_dir, CreatePrivDir}
{multiply_timetraps, M}
{scale_timetraps, Bool}
{repeat, N}
{duration, DurTime}
{until, StopTime}
{force_stop, Bool}
{decrypt, DecryptKeyOrFile} % Variables Supported
{refresh_logs, LogDir} % Variables Supported
{logopts, LogOpts}
{basic_html, Bool}
{ct_hooks, CTHs}
{enable_builtin_hooks, Bool}

[Tristan Sloughter]

I'd suggest publishing this directly, before review to http://erlware.github.com/sinan/

That way it is easier to read :). No one will stumble on it before any fixes are added I'm sure.

Tristan

--
You received this message because you are subscribed to the Google Groups "erlware-dev" group.
To post to this group, send email to erlwa...@googlegroups.com.
To unsubscribe from this group, send email to erlware-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/erlware-dev?hl=en.

[Eric Merritt]

this is the actual in source help documentation. It makes it slightly
harder to publish in that way

[Tristan Sloughter]

Huh? Why would this not be a page for the website?

[Eric Merritt]

Well, I think its important to have good documentation in the app.
that is you can do

$> sinan help ct

and get comprehensive documentation for the ct app. I also dislike
duplicating documentation, so its more important that it be in 'help'
then that it be on a page.

I would like to have a solution that solves both.

[Tristan Sloughter]

Very confused. What you posted looked damn well like Markdown to me. Which means it can simply be placed on the website as well.

Duplicating is GOOD. Being able to duplicate to from a single source file would be the best, but if not possible it doesn't change that it should be in both places.

People looking at sinan and its features are going to go to the website and if they see common test documentation they will be intrigued.

Having to wait till that person downloads sinan, runs it to see there is a help command, then that you can send a command to the help command and get the docs with 'sinan help ct' just destroyed conversion rates :P

[Eric Merritt]

On Sat, May 5, 2012 at 12:20 PM, Tristan Sloughter
<tristan....@gmail.com> wrote:
> Very confused. What you posted looked damn well like Markdown to me. Which
> means it can simply be placed on the website as well.

It is mardown. The built in help is all in markdown as well. Why
introduce another standard?

> Duplicating is GOOD. Being able to duplicate to from a single source file
> would be the best, but if not possible it doesn't change that it should be
> in both places.

Having the information be published in multiple place is good.
Duplicating is bad.

>
> People looking at sinan and its features are going to go to the website and
> if they see common test documentation they will be intrigued.

True, but they need it when they are trying to figure out how to use a task.

>
> Having to wait till that person downloads sinan, runs it to see there is a
> help command, then that you can send a command to the help command and get
> the docs with 'sinan help ct' just destroyed conversion rates :P

agreed. on this one. I will think about how to fix that.

[Tristan Sloughter]

I never said another standard. And I think published in multiple places outweighs duplication.

And I never said to get rid of it from 'sinan help ct', I just want it on the website.

[Eric Merritt]

Fair enough. I just dont like that they will get out of sync. However,
I think that once the docs move from the wiki to the manual (in the
docs dir). I can fix that problem.

On Sat, May 5, 2012 at 12:30 PM, Tristan Sloughter

[Tristan Sloughter]

Understood.

[Eric Merritt]

https://github.com/erlware/sinan/wiki/Common-Test-Task

On Sat, May 5, 2012 at 12:36 PM, Tristan Sloughter

[Eric Merritt]

Just as a follow up I *do* want feedback on the content itself.