Parser could allow "non-table comments"

[GoogleCodeExporter]

Today, a robot table starts with an HTML <table> tag and ends with the
matching </table>.

Also, currently I know of no way to write interleaved testing code and
pretty HTML explanations.

The parser could easily be changed to allow the second, changing the first:

| Test   | Action          | Argument | Argument |
| # not-pretty comment that explains stuff | | | |
| A test | A keyword       | Arg      |          |
| # more explanations                      | | | |
|        | Foo             | Bar      |          |

Could instead be written as:

| Test   | Action          | Argument | Argument |

This is outside the table. Therefore, the parser doesn't care a bit and we
can write paragraphs of text, add pictures, do whatever we feel like doing.

<H1>So here's a pretty explanation of the next test</H1>

| A test | A keyword       | Arg      |          |

The next keyword is gonna foo the bar.

Isn't this much prettier than a "# comment" inside the table?

|        | Foo             | Bar      |          |

How is this done?

Instead of the parser ignoring tables that don't start with either
"Settings", "Variables", "Keywords" or "Tests", the parser will only ignore
tables starting with "Comment" (or another selected keyword). Also, it will
only emit "end of table" tokens upon meeting a new table that starts with
either "Settings", "Variables", "Keywords" or "Tests".

This enhancement would allow me to write much more readable acceptance
tests in robot framework without detracting a bit from the power of the
language.

It would only require changes to this area in parsing/htmlreader.py:

# from
                table_name = self.current_row[0]
                if self.data.start_table(table_name):
                    self.state = self.PROCESS
                else:
                    self.state = self.IGNORE

# to something like
                table_name = self.current_row[0]
                self.data.start_table(table_name):
                self.state = self.PROCESS

and in parsing/rawdata.py:

# from
    def start_table(self, name):
        """Makes rawdata instance ready to receive new data

        This method should be called with table's name before adding table's
        data with 'add_row'.
        Returns False if data from specified table will not be processed.
        Client should thus check the return value and only call 'add_row' if
        it is True.
        """
        name = self._collapse_whitespace(name)
        table, data = self._get_table_and_data(name)
        if table is not None:
            self._table = table(name, self.source, data, self._syslog)
        else:
            self._table = None
        return self._table is not None
# to something like
    def start_table(self, name):
        """Makes rawdata instance ready to receive new data

        This method should be called with table's name before adding table's
        data with 'add_row'.
        Returns False if data from specified table will be processed as
part of pre-existing table.
        """
        name = self._collapse_whitespace(name)
        table, data = self._get_table_and_data(name)
        if table is not None:
            self._table = table(name, self.source, data, self._syslog)
        else:
            if self._table is None:
                throw RuntimeException("First table has to start with
table-type row")
        return table is not None

These aren't tested, of course, and should only be seen as pseudo-code.
They also lack support for non-robot tables. ("comment tables").

Original issue reported on code.google.com by SonOfLi...@gmail.com on 4 Dec 2008 at 1:37

[GoogleCodeExporter]

You can already now have multiple test case tables (and other tables as well) 
in the
test data. For example the Quick Start Guide [1] uses this approach. The first 
cell
of the table needs to have 'Test Case' (or something else for other tables) in 
it,
though, but if you want you can use CSS to hide the first row altogether.

[1] 
http://robotframework.googlecode.com/svn/trunk/doc/quickstart/quickstart.html

The problem with having multiple tables is that Robot IDE doesn't support that 
at all
currently. More importantly, adding support for it would be _really_ big task 
and
isn't likely to be done in foreseeable future. We will, on the other hand, 
enhance
RIDE in the current iteration so that it will support text between different 
tables
(currently it ignores everything outside tables).

Another problem with RIDE is that it totally ignores comments created with '#'
character [2]. This, as well as ignoring the data outside tables, is due to the 
fact
that RIDE uses Robot Framework's internal modules for processing the data and RF
itself simply ignores everything that's not related to the actual test data. 

[2] http://code.google.com/p/robotframework-ride/wiki/Comments 

In general you shouldn't need comments in the test data that much. Most of the 
time
you should be able to use so describing keyword names that they need no 
commenting.
Test suite and test case documentations are also natural places to add some more
information.

The reason I wrote so much about RIDE is that I believe in the future that's 
what
most people will be using for editing the test data. Adding such features to 
the core
framework that aren't easily supported by RIDE isn't thus a very good idea.

Original comment by pekka.klarck on 10 Dec 2008 at 12:14

[GoogleCodeExporter]

The best place to implement this feature would probably be parsing/htmlreader.py
file. HtmlReader class has a state machine that is used to decide what to do 
with the
encountered data. It ought to be possible to change it so that when a table 
ends its
type is stored, and if next table doesn't start with a known table identifier 
the old
identifier is used. 

The biggest problem of implementing this, regardless on the implementation, is 
that
the change is backwards incompatible. If anyone has used table outside the 
actual
test data tables they would now be considered part of the test data. Because of 
this
problem, and the fact that RIDE cannot support multiple tables, I'm getting a 
feeling
that implementing this isn't too good idea. I'm still leaving this issue open 
so that
others can comment.

Original comment by pekka.klarck on 10 Dec 2008 at 12:24

[GoogleCodeExporter]

I am suggesting the second kind of change (see my original suggestion, I show an
implementation like you suggested).

It is indeed non-backward-compatible, but it would make writing executable user
stories in robot so much better that I think it is worth it. Perhaps a 
command-line
option could be created to enable new behavior.

Original comment by SonOfLi...@gmail.com on 10 Dec 2008 at 5:53

[GoogleCodeExporter]

We decided not to implement this due to reasons explained below. First too are
explained in more detain in comment 1.

1) You can have multiple tables my having suitable table headers (which can 
even be
hidden with CSS).

2) Ride does not support having multiple tables.

3) You can format table like

+-----------+------------+----------+
| Test Case | Argument   | Argument |
+-----------+------------+----------+
| My Test   | My Keyword | arg      |
+-----------+------------+----------+
| # A comment here. Note that cols  |
| have been merged.                 |
+-----------+------------+----------+
|           | Another KW |          |
+-----------+------------+----------+

Original comment by pekka.klarck on 19 Jan 2009 at 2:51

• Changed state: WontFix

[GoogleCodeExporter]

Ooops, forgot the most important reason not to fix this:

The change would be backwards incompatible. We needed to deprecate the change 
first,
document everything in details, etc. That's just too much work considering the 
points
in the previous comment.

Original comment by pekka.klarck on 19 Jan 2009 at 2:53