expected_output 1.2.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 54

Keep multiline test case inputs and outputs out of your Dart test code, and write them directly as text files.

Example

Take the following test case for String's toUpperCase():

void main() {
  test('Works on multiline strings', () {
    var input = r'''This is the first line.
This is another line.

This is another paragraph.''';

    var expectedOutput = r'''THIS IS THE FIRST LINE.
THIS IS ANOTHER LINE.

THIS IS ANOTHER PARAGRAPH.''';

    expect(input.toUpperCase(), equals(expectedOutput));
  });
}

Multiline strings break the visual flow of code indentations. Additionally, when newline characters are important, you may not be able to just write a newline before the closing ''';, which makes it hard to scan for where multiline Strings begin and end. Instead, let's write this test case, and a few more, in a separate text file:

>>> Works on simple strings
This is a single line.
<<<
THIS IS A SINGLE LINE.
>>> Does nothing to upper case strings
THIS IS ALREADY UPPER CASE.
<<<
THIS IS ALREADY UPPER CASE.
>>> Works on multiline strings
This is the first line.
This is another line.

This is another paragraph.
<<<
THIS IS THE FIRST LINE.
THIS IS ANOTHER LINE.

THIS IS ANOTHER PARAGRAPH.

We can quickly create tests over these data cases with some Dart:

library touppercase.tests;

void main() {
  for (var dataCase in dataCasesUnder(library: #touppercase.tests)) {
    test(dataCase.testDescription, () {
      var actualOutput = dataCase.input.toUpperCase();
      expect(actualOutput, equals(dataCase.expectedOutput));
    });
  }
}

If our test is located at to_upper_case_package/test/to_upper_case_test.dart, then dataCasesUnder will look for files ending in .unit in the same directory as the library. So our text file with the test cases should be, perhaps, to_upper_case_package/test/cases.unit.

(Note: Why the weird library symbols? This is the simplest way to locate a directory or file relative to Dart source. Hopefully a temporary issue.)

API

The expected_output API is small. Here's the gist:

  • dataCases(directory: 'some/directory')
    Iterate over all of the .unit files in 'some/directory', yielding DataCases with input/output information.

  • dataCasesUnder(library: #your.test.library)
    Iterate over all of the .unit files in the directory where #your.test.library Dart library is declared. This is just a convenience method so that you don't need to import mirrors in your test.

  • dataCasesInFile(path: 'path/to/your/data.unit')
    Iterate over all of the DataCases found in 'path/to/your/data.unit'.

  • testDataCases(
        directory: 'some/directory',
        testBody: (DataCase dataCase) {
          expect(something(dataCase.input), dataCase.expected_output);
        });
    

    Iterate over all of the DataCases found in 'some/directory', declaring a test package test case for each, using testBody as the body of the test case.

  • testDataCasesUnder(
        library: #your.test.library,
        testBody: (DataCase dataCase) {
          expect(something(dataCase.input), dataCase.expected_output);
        });
    

    Iterate over all of the DataCases found in the directory where #your.test.library Dart library is declared, declaring a test package test case for each, using testBody as the body of the test case.

Front Matter

Each data file can start with a section called front matter, which can be used as comments or as configuration. Here is an example:

This is front matter. It is free form,
and can span multiple lines.
>>> Data Case 1
Input 1
<<<
Expected Output 1
>>> Data Case 2
Input 2
<<<
Expected Output 2

Each data case parsed from this data file will include a front_matter member, which has the value This is front matter. It is free form,\nand can span multiple lines..

Front matter does not necessarily ever need to be used in a test; it can act as a file comment. Alternatively, you may parse it as configuration, perhaps writing front matter as JSON or YAML.

When to use

This package is not very broad purposed, and is probably appropriate for only very specific functionality testing. It has been very useful for testing packages that primarily transform one block of text into another block of text.

This package is also mostly useful when the different ways to configure the processing is very limited. In these cases, the Dart code that receives the test cases and asserts over them can be very brief, and developers can focus on just writing the data test cases.

This package is also most useful when whitespace is ever significant. In cases like this, multiline strings cannot fake indentation, and it may be harder for the developer to track whitespace when writing a test case. In contrast, it is probably much easier to write input and expected output in simple text blocks in simple text files. Examples would include a Markdown parser that needs to parse indented list continuations or indented code blocks, and text formatters that need to test specific indentation in the output.

1.2.0

  • Add support for front matter.

1.1.0

  • Add test helpers testDataCases and testDataCasesUnder.

1.0.0

  • Initial release, includes all functionality found in the README.

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  expected_output: "^1.2.0"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:expected_output/expected_output.dart';
        
Version Uploaded Documentation Archive
1.2.0 Jul 11, 2017 Go to the documentation of expected_output 1.2.0 Download expected_output 1.2.0 archive
1.1.0 Jun 8, 2017 Go to the documentation of expected_output 1.1.0 Download expected_output 1.1.0 archive
1.0.0 Jun 8, 2017 Go to the documentation of expected_output 1.0.0 Download expected_output 1.0.0 archive

Analysis

We analyzed this package on Apr 23, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.49.0
  • pana: 0.10.6

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
9 / 100
Health:
Code health derived from static analysis. [more]
100 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
54
Learn more about scoring.

Platforms

Detected platforms: other

Primary library: package:expected_output/expected_output.dart with components: io, isolate, mirrors.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use expected_output.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.19.0 <2.0.0
path ^1.4.1 1.5.1
test ^0.12.20 0.12.35
Transitive dependencies
analyzer 0.31.1 0.31.2-alpha.1
args 1.4.2
async 2.0.6
barback 0.15.2+15
boolean_selector 1.0.3
charcode 1.1.1
cli_util 0.1.2+1
collection 1.14.9
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
front_end 0.1.0-alpha.9 0.1.0-alpha.11
glob 1.1.5
html 0.13.3
http 0.11.3+16
http_multi_server 2.0.4
http_parser 3.1.1
io 0.3.2+1
isolate 1.1.0 2.0.0
js 0.6.1
kernel 0.3.0-alpha.9 0.3.0-alpha.11
logging 0.11.3+1
matcher 0.12.2
meta 1.1.2
mime 0.9.6
multi_server_socket 1.0.1
node_preamble 1.4.0
package_config 1.0.3
package_resolver 1.0.2
plugin 0.2.0+2
pool 1.3.4
pub_semver 1.3.7
shelf 0.7.2
shelf_packages_handler 1.0.3
shelf_static 0.2.7
shelf_web_socket 0.2.2
source_map_stack_trace 1.1.4
source_maps 0.10.4
source_span 1.4.0
stack_trace 1.9.2
stream_channel 1.6.5
string_scanner 1.0.2
term_glyph 1.0.0
typed_data 1.1.5
utf 0.9.0+4
watcher 0.9.7+7
web_socket_channel 1.0.7
yaml 2.1.13