pageloader 3.0.2

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 83

PageLoader

Build Status

A framework for creating page objects for in-browser tests or Webdriver tests.

Starting with version 3.0.0, PageLoader is changed significantly from version 2.X.X. Refer to "What Changed since version 2?" section for more details.

A strongly typed implementation of PageLoader for Dart and does not depend on dart:mirrors, which is slated for removal in Dart 2.0. If you're starting fresh with Dart UI testing, we recommend you use PageLoader version 3.X.X. PageLoader version 2.X.X and below is deprecated and no longer supported.

Migration guide will be added shortly.

If you are looking for the legacy version of PageLoader (with mirrors), refer to the branch "2-stable" which is in sync with version 2.2.7.

What Changed since version 2?

There are three big changes here:

  1. Instead of using dart:mirrors, code generation is used. Unfortunately this means extra boilerplate code. Every PageObject you write will also now have a generated component.

  2. Everything is lazily loaded by default. Lazy<T> and @optional from version 2.X.X no longer exists.

  3. Sync-ification of the API, which means significantly fewer Futures and awaits.

Boilerplate

Version 3.0.0 and above uses Dart code-gen, so the generator needs a couple of hints to trigger the generation step. The boilerplate is:

// Assume this file is called: 'my_po.dart'
import 'package:pageloader/pageloader.dart';

part 'my_po.g.dart';

@PageObject()
abstract class MyPO {
  MyPO();
  factory MyPO.create(PageLoaderElement context) =
      $MyPO.create;
}

PageObject containing Dart files must be in test/... directory for the code generation step to occur.

For example:

  1. test/page_objects/special_po.dart will work
  2. test/src/page_objects/special_po.dart will work
  3. lib/src/foo/my_po.dart will not work
    • File is located in lib/... directory; must be in test/...

The above restriction is only temporary and will be relaxed in the future. But by convention, this should be done even after the requirement is relaxed.

Above is the bare minimum boilerplate code needed for a PageObject. Feel free to cut/paste this when starting new page objects.

To construct a PageObject, use this create constructor on either HtmlPageLoaderElement or WebdriverPageLoaderElement.

HtmlPageLoaderElement example:

import 'package:pageloader/html.dart';

Element myElement = ...;
final context = HtmlPageLoaderElement.createFromElement(myElement);
final myPO = MyPO.create(context);

createFromElement has an additional named argument SyncFn externalSyncFn. This synchronizing function is called on asynchronous events (click, type, etc.) and ensures that these events have time to take into effect. By default, this is a no-op function.

An example of a custom sync function:

HtmlPageLoaderElement.createFromElement(myElement,
        externalSyncFn: (Future action()) async {
      await action();
      // Wait longer than normal
      for (var i = 0; i < 1000; i++) {
        await Future.value();
      }
    });

Note that this externalSyncFn is then called on every asynchronous method of that HtmlPageLoaderElement as well as its childrens' HtmlPageLoaderElements. Refer to "What is synchronous/asynchronous" section for more information about which events are asynchronous.

WebdriverPageLoaderElement example:

import 'package:pageloader/webdriver.dart';
import 'package:webdriver/sync_io.dart';

String pagePath = ...; // Page uri path
Webdriver driver = ...; // Refer to Webdriver package documentation
WebDriverPageUtils loader = WebDriverPageUtils(driver);
driver.get(pagePath);

WebDriverPageLoaderElement context = loader.root;
WebDriverMouse get mouse = loader.mouse;

final myPO = MyPO.create(context);

// ...run tests...

loader = null;
driver.quit();

How do I trigger the generation step?

pub run build_runner build

Lazy Loading

Starting from version 3, all elements are lazy.

final myPO = MyPO.create(pageLoaderElementContext);

Nothing happens with the browser at this point. You need to either read information from the page or interact with the browser:

final anotherPO = myPO.anotherPO; // Still does nothing
anotherPO.click(); // Finds the page object, and clicks it
expect(anotherPO.innertext, 'text'); // Finds page object again and reads inner text

This matches how the rest of the API worked: you read attributes lazily, you read text lazily, and now you find elements lazily.

Existence Checking

In PageLoader version 2.X.X, the @optional tag was used to mark some entity as possibly not existing. For example:

// Pageloader2
class MyPO {
  @optional
  @ByTagName('maybe-here')
  PageLoaderElement someElement;
  
  @optional
  @ByTagName('also-maybe-here')
  SomePO somePO;
}

In the case that either someElement or somePO did not exist, it would have null value.

Starting from version 3, @optional is removed and these entities no longer return as null. For PageLoaderElement, you directly use its .exists getter to check or use provided matchers.

import 'package:pageloader/testing.dart';

PageLoaderElement myElement = ...;
expect(myElement.exists, isTrue);
expect(myElement, exists);

For PageObjects, use provided matchers:

import 'package:pageloader/testing.dart';

SomePO somePO = SomePO.create(context);
expect(somePO, exists);

What is synchronous/asynchronous?

PageLoaderElements in version 3.0.0 and above use both synchronous and asynchronous calls in the API. The basic rule is as follows: any call that cannot change the DOM is synchronous, and any call that can change the DOM is asynchronous.

For example, reading DOM attributes or finding elements is synchronous. Click and typing are still asynchronous.

Future<bool> doSomething() async {
  await myPageElement.click();
  final text = myPageElement.innerText;
  await myOtherElement.type(text);
  return myOtherElement.attributes['someattr'] == 'value';
}

Why do we still have async methods?

Interactions, e.g. clicking, typing, etc. still return Futures. Why?

Remember that component tests actually run in the browser, with the component, in the same thread. Dart (like JavaScript) has no threads, so if the test is doing something then the component is not. If the whole test is synchronous it'll execute start to finish without any pause, as one massive action in the event loop.

So, we'll type something, but the component won't update... because it can't actually execute. And the next line, where we assert something about the component it will fail:

myPo.type('someKeys');
expect(myPo.someElement.innerText, 'someKeys'); // This won't work!

We need to allow the component to update. Having interactions with the browser (i.e. clicking, typing) be asynchronous allows the component to change:

await myPo.type('someKeys'); // Generates a Future.
expect(myPo.someElement.innerText, 'someKeys'); // This is fine now.

Inheritance

With code-gen, direct inheritance is no longer allowed. However, you can use mixins or delegation to keep 'inheritance-like' behavior in your code.

Consider:

@PageObject()
abstract class BasePO {
  // ... boilerplate code ...
  
  @ByTagName('my-widget')
  MyWidgetPO get myWidget;
  
  String get widgetInnerText => myWidget.innerText;
}

@PageObject()
abstract class ExtraPO extends BasePO { // 'extends' not allowed
  // ... boilerplate code ...
  
  @ByTagName('extra-widget')
  MyExtraWidgetPO get extraWidget;
}

Delegation method fix:

@PageObject()
abstract class BasePO {
  // ... boilerplate code ...
  
  @ByTagName('my-widget')
  MyWidgetPO get myWidget;
  
  String get widgetInnerText => myWidget.innerText;
}

@PageObject()
abstract class ExtraPO {
  // ... boilerplate code ...
  
  @root
  BasePO get _basePO;
  
  MyWidgetPO get myWidget => _basePO.myWidget;
  
  String get widgetInnerText => _basePO.widgetInnerText;
  
  @ByTagName('extra-widget')
  MyExtraWidgetPO get extraWidget;
}

Mixin method fix:

@PageObject()
abstract class BasePO extends Object with BasePOMixin {
  // This should ONLY have the constructors
  BasePO();
  factory BasePO.create(PageLoaderElement context) =
     $BasePO.create;
}

@PageObject()
abstract class BasePOMixin {
  // Note that here are no constructors here.
  
  @ByTagName('my-widget')
  MyWidgetPO get myWidget;
  
  String get widgetInnerText => myWidget.innerText;
}

@PageObject()
abstract class ExtraPO extends Object with BasePOMixin {
  // ... boilerplate code ...
  
  // No need to define 'myWidget' and 'widgetInnerText' here.
  // The mixin will handle these.
  
  @ByTagName('extra-widget')
  MyExtraWidgetPO get extraWidget;
}

3.0.2

  • Support the latest release of package:built_value, package:quiver, and package:source_gen.

3.0.1

  • Support the latest release of package:build.

3.0.0

  • Added lookup constructor that can also be delegated as another constructor.
  • Improved HtmlMouse to send more accurate mouse events. moveTo API changed.
  • Added clickOutside() API to PageLoaderElement.
  • Lint fixes and suppression in generated code.
  • Remove unnecessary usages of new and const.
  • Bump webdriver to v2.0.0.
  • Update to the latest source_gen. This generator can now be used with other generators that want to write to .g.dart files without a manual build script.
  • Breaking: The header builder option is no longer supported.
  • @EnsureTag is marked as deprecated. Will be removed in a future release.
  • Add listeners into WebdriverPageLoaderElement if searching for descendants.
  • Add @ByCheckTag() as a convenience annotation that can be used in place of @ByTagName(...).
  • Dart 2 compatible version that uses code generation instead of mirrors.
  • Dropped @FirstByCss() annotation class. Use @First(ByCss(...)).
  • Added matchers for PageLoaderElement and PageObjects.

2.2.6

  • Fix static analysis warnings for Dart and DDC 1.23.
  • Remove PageLoaderElement.attributes, and class WithAttribute.
  • Add properties and attributes fields to PageLoaderElement.
  • Deprecate PageLoaderElement.seleniumAttributes.

2.2.5

  • Bump minimum SDK version to 1.21.0.
  • Pageloader now builds and tests with Bazel.
  • Add new seleniumAttributes getter to PageLoaderElement.

2.2.4

  • Remove broken KeyEvent use
  • Added docs to PageLoaderElement

2.2.3

  • remove unnecessary casts
  • Make getInstance a generic method

2.2.2

  • strong mode fixes
  • added changelog

2.2.1

  • Fix more strong mode errors.

2.2.0

  • Fix some strong mode errors.

2.1.2

  • Add FirstByCss finder to help support recursively defined components.

2.0.2

  • Fixed compatibility issue with the webdriver package's awaitChecking.

2.0.1

  • No functional change. Test Setup has been refactored to eliminate code duplication.

2.0.0

  • No functional change, just bumping the version number.

Use this package as a library

1. Depend on it

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


dependencies:
  pageloader: ^3.0.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

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

3. Import it

Now in your Dart code, you can use:


import 'package:pageloader/pageloader.dart';
  
Version Uploaded Documentation Archive
3.0.2 Oct 26, 2018 Go to the documentation of pageloader 3.0.2 Download pageloader 3.0.2 archive
3.0.1 Oct 9, 2018 Go to the documentation of pageloader 3.0.1 Download pageloader 3.0.1 archive
3.0.0 Aug 7, 2018 Go to the documentation of pageloader 3.0.0 Download pageloader 3.0.0 archive
2.2.6 Apr 5, 2017 Go to the documentation of pageloader 2.2.6 Download pageloader 2.2.6 archive
2.2.5 Jan 12, 2017 Go to the documentation of pageloader 2.2.5 Download pageloader 2.2.5 archive
2.2.4 Nov 18, 2016 Go to the documentation of pageloader 2.2.4 Download pageloader 2.2.4 archive
2.2.3 Sep 23, 2016 Go to the documentation of pageloader 2.2.3 Download pageloader 2.2.3 archive
2.2.2 Sep 14, 2016 Go to the documentation of pageloader 2.2.2 Download pageloader 2.2.2 archive
2.2.1 Aug 17, 2016 Go to the documentation of pageloader 2.2.1 Download pageloader 2.2.1 archive
2.2.0 Aug 15, 2016 Go to the documentation of pageloader 2.2.0 Download pageloader 2.2.0 archive

All 33 versions...

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

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

  • Dart: 2.1.0
  • pana: 0.12.7

Platforms

Detected platforms: Flutter, other

Primary library: package:pageloader/pageloader.dart with components: io.

Health suggestions

Fix lib/src/generators/methods/unannotated_method.dart. (-1.99 points)

Analysis of lib/src/generators/methods/unannotated_method.dart reported 4 hints:

line 91 col 23: 'element' is deprecated and shouldn't be used.

line 96 col 26: 'element' is deprecated and shouldn't be used.

line 96 col 44: 'element' is deprecated and shouldn't be used.

line 101 col 23: 'element' is deprecated and shouldn't be used.

Fix lib/src/generators/pageobject_generator.dart. (-1.49 points)

Analysis of lib/src/generators/pageobject_generator.dart reported 3 hints:

line 77 col 40: 'element' is deprecated and shouldn't be used.

line 88 col 39: 'element' is deprecated and shouldn't be used.

line 89 col 57: 'element' is deprecated and shouldn't be used.

Fix lib/src/webdriver/webdriver_mouse.dart. (-1.49 points)

Analysis of lib/src/webdriver/webdriver_mouse.dart reported 3 hints:

line 36 col 22: 'mouse' is deprecated and shouldn't be used.

line 45 col 15: 'mouse' is deprecated and shouldn't be used.

line 55 col 22: 'mouse' is deprecated and shouldn't be used.

Fix additional 4 files with analysis or formatting issues. (-3.99 points)

Additional issues in the following files:

  • lib/src/webdriver/webdriver_page_loader_element.dart (3 hints)
  • lib/src/generators/methods/setter.dart (2 hints)
  • lib/src/html/html_mouse.dart (2 hints)
  • lib/src/html/html_page_loader_element.dart (1 hint)

Maintenance suggestions

Maintain an example. (-10 points)

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 pageloader.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
analyzer ^0.32.5 0.32.6 0.34.0
build >0.12.7 <2.0.0 1.0.1
build_config ^0.3.1 0.3.1+4
built_value ^6.1.0 6.1.6
matcher ^0.12.0+1 0.12.4
quiver >=2.0.0 <3.0.0 2.0.1
source_gen ^0.9.1+3 0.9.1+3
webdriver ^2.0.0 2.0.0
Transitive dependencies
archive 2.0.4
args 1.5.1
async 2.0.8
built_collection 4.1.0
charcode 1.1.2
collection 1.14.11
convert 2.0.2
crypto 2.0.6
csslib 0.14.6
dart_style 1.1.3 1.2.1
fixnum 0.10.9
front_end 0.1.4+2 0.1.7
glob 1.1.7
html 0.13.3+3
json_annotation 2.0.0
kernel 0.3.4+2 0.3.7
logging 0.11.3+2
meta 1.1.6
package_config 1.0.5
plugin 0.2.0+3
pub_semver 1.4.2
pubspec_parse 0.1.2+3
source_span 1.4.1
stack_trace 1.9.3
string_scanner 1.0.4
sync_http 0.1.3
typed_data 1.1.6
utf 0.9.0+5
watcher 0.9.7+10
yaml 2.1.15
Dev dependencies
build_runner ^1.0.0
built_value_generator ^6.0.0
path ^1.3.6 1.6.2
test ^1.2.0