commonComponentTests function

  1. @isTestGroup
void commonComponentTests(
  1. BuilderOnlyUiFactory<UiProps> factory, {
  2. bool shouldTestPropForwarding = true,
  3. List unconsumedPropKeys = const [],
  4. List skippedPropKeys = const [],
  5. List getUnconsumedPropKeys(
    1. PropsMetaCollection
    )?,
  6. List getSkippedPropKeys(
    1. PropsMetaCollection
    )?,
  7. Map nonDefaultForwardingTestProps = const {},
  8. bool shouldTestClassNameMerging = true,
  9. bool shouldTestClassNameOverrides = true,
  10. bool ignoreDomProps = true,
  11. bool shouldTestRequiredProps = true,
  12. @Deprecated('This flag is not needed as the test will auto detect the version') bool? isComponent2,
  13. dynamic childrenFactory()?,
})

Run common component tests around default props, prop forwarding, class name merging, and class name overrides.

Best used within a group() within a component's test suite:

main() {
  group('SomeComponent', () {
    // other tests

    group('common component functionality:', () {
      commonComponentTests(SomeComponentFactory);
    });
  });
}

Options:

shouldTestPropForwarding - whether testPropForwarding will be called.

Optionally, set ignoreDomProps to false if you want to test the forwarding of keys found within DomProps.

shouldTestRequiredProps - whether testRequiredProps will be called. Note: All required props must be provided by factory.

shouldTestClassNameMerging - whether testClassNameMerging will be called.

shouldTestClassNameOverrides - whether testClassNameOverrides will be called.

childrenFactory returns children to be used when rendering components.

This is necessary for components that need children to render properly.

unconsumedPropKeys (or getUnconsumedPropKeys for new boilerplate) should be used when a component has props as part of it's definition that ARE forwarded to its children (ie, a smart component wrapping a primitive and forwarding some props to it).

By default, testPropForwarding tests that all consumed props are not forwarded, so you can specify forwarding props in unconsumedPropKeys (which gets flattened into a 1D array of strings).

When the forwarding of certain props is ambiguous (see error message in testPropForwarding), you can resolve this by specifying nonDefaultForwardingTestProps, a map of prop values that aren't the same as the forwarding target's defaults.

If nonDefaultForwardingTestProps can't be used for some reason, you can skip prop forwarding tests altogether for certain props by specifying their keys in skippedPropKeys (or getSkippedPropKeys for new boilerplate) (which gets flattened into a 1D array of strings).

Implementation

@isTestGroup
void commonComponentTests(BuilderOnlyUiFactory factory, {
  bool shouldTestPropForwarding = true,
  List unconsumedPropKeys = const [],
  List skippedPropKeys = const [],
  List Function(PropsMetaCollection)? getUnconsumedPropKeys,
  List Function(PropsMetaCollection)? getSkippedPropKeys,
  Map nonDefaultForwardingTestProps = const {},
  bool shouldTestClassNameMerging = true,
  bool shouldTestClassNameOverrides = true,
  bool ignoreDomProps = true,
  bool shouldTestRequiredProps = true,
  @Deprecated('This flag is not needed as the test will auto detect the version')
  bool? isComponent2,
  dynamic childrenFactory()?
}) {
  childrenFactory ??= _defaultChildrenFactory;

  if (shouldTestPropForwarding) {
    _testPropForwarding(
      factory,
      childrenFactory,
      unconsumedPropKeys: unconsumedPropKeys,
      skippedPropKeys: skippedPropKeys,
      getUnconsumedPropKeys: getUnconsumedPropKeys,
      getSkippedPropKeys: getSkippedPropKeys,
      ignoreDomProps: ignoreDomProps,
      nonDefaultForwardingTestProps: nonDefaultForwardingTestProps,
    );
  }

  if (shouldTestClassNameMerging) {
    testClassNameMerging(factory, childrenFactory);
  }
  if (shouldTestClassNameOverrides) {
    testClassNameOverrides(factory, childrenFactory);
  }
  if (shouldTestRequiredProps && assertsEnabled()) {
    testRequiredProps(factory, childrenFactory);
  }
}