NvGolden (v1.0.0-beta)

Table of Contents

NvGolden

init

The init method has to be called before running any golden test which includes text or icons. The init method attempts to load all fonts registered within the pubspec.yaml file. If init is unable to load your fonts you can manually load them using NvGolden.loadFont(...). Without your fonts being loaded, your screenshots will display black squares instead of readable text.

setUpAll(NvGolden.init);

// Or alternatively (in case your fonts aren't automatically picked up)
setUpAll(() => Future.wait([
    NvGolden.init(),
    NvGolden.loadFont(
      name: 'Roboto',
      paths: ['lib/fonts/Roboto-Regular.ttf'],
    ),
  ]),
);

singular

The singular constructor allows you to render a single scenario. This is especially useful when added to regular widget tests so you can see what is being rendered during your test.

testWidgets('your test name', (tester) async {
    final nvGolden = NvGolden.singular(
      widget: nvWrapper.wrap(YourWidget(...)),
      screen: Screen(size: Size(200, 100)),
    );

    await tester.createGolden(nvGolden, 'your-golden-name');

    // Expect statements have to happen after the createGolden or createSequenceGolden call
    // because those calls also take care of pumping your widget!
    expect(find.byType(YourWidget), findsOneWidget);
});

grid

The grid constructor allows you to render a several golden scenarios into a single file.

testWidgets('your test name', (tester) async {
  final nvGolden = NvGolden.grid(
    nrColumns: 2, 
    screen: Screen(size: Size(200, 100)),
  )
    ..addScenario(
      name: 'Icon 1',
      widget: nvWrapper.wrap(YourWidget(...)),
    )
    ..addScenario(...)
    ..addScenario(...)
    ..addScenario(...);

    await tester.createGolden(nvGolden, 'your-golden-name');

    // Expect statements have to happen after the createGolden or createSequenceGolden call
    // because those calls also take care of pumping your widget!
    // Keep in mind that your widget will be rendered once per scenario!
    expect(find.byType(YourWidget), findsNWidgets(4));
});

devices

The devices constructor renders every scenario once per device. It is highly recommended to add these test on a page/screen level with a very small device (such as the Device.iphone5s) and a rather large one (such as the 'Device.iphone12proMax`) to ensure your designs look nice on big screens and don't overflow on small ones.

testWidgets('your test name', (tester) async {
  final nvGolden = NvGolden.devices(
    deviceSizes: [Device.iphone5s, Device.iphone12proMax],
  )
  ..addScenario(
    name: 'scenario name',
    widget: YourWidgt(...),
  )
  ..addScenario(...);

  await tester.createGolden(nvGolden, 'your-golden-name');

  // Expect statements have to happen after the createGolden or createSequenceGolden call
  // because those calls also take care of pumping your widget!
  // Keep in mind that your widget will be rendered once per Device for every scenario!
  expect(find.byType(YourWidget), findsNWidgets(4));
});

Golden Creation

The golden creation methods are extensions on the WidgetTester instance. They'll take an instance of NvGolden as the first argument and the name of the golden file as the second one.

createGolden

The createGolden(...) method renders the NvGolden instances scenario(s). For singular Goldens it will merely render the widget while it will add a title for both the grid and the devices constructor.

await tester.createGolden(nvGolden, 'your-golden-name');

Example Grid:

Example Device:

createSequenceGolden

During widget testing one might also want to tap certain elements on the screen (maybe even several of them in order). This is where Sequence testing comes in. It renders where the tap event(s) occurred to also add a visible check whether the correct element was clicked or not.

createSequenceGolden(...) is only compatible with NvGolden.singular(...).

await tester.createSequenceGolden(
  nvGolden,
  'your-golden-name',
  // Renders taps and optionally applies them to the pumped widget
  gestures: [NvGesture.tap(finder: finder)],
);

Example:

Display

The golden builder methods need to know how much space is available to the widget being rendered.

Device

Device is an abstract class holding some common test devices readily available for you.

Screen

You can also create your own Device using the Screen class.

Screen(
   name: 'Iphone 12 Pro',
  size: Size(390, 844),
  safeArea: const EdgeInsets.fromLTRB(0.0, 47.0, 0.0, 34.0),
);

Gestures

createSequenceGolden allows for interactive golden testing. All gestures are rendered on the golden first and applied after the golden file has been saved. The result of a sequence golden will be used as the input for the following sequence golden.

tap

tap simulates a tap event on the specified finder. This is currently the only Gesture implemented. More are soon to come.

Libraries

create_golden
font_loader
iterable_extensions
nv_font_loader
nv_gesture
nv_golden
nv_golden_base
nv_golden_icons
Flutter icons NvGoldenIcon Copyright (C) 2022 by original authors @ fluttericon.com, fontello.com This font was generated by FlutterIcon.com, which is derived from Fontello.
nv_golden_multiple
nv_golden_singular
scenario
screen
test_asset_bundle
widget_wrapper