Annotation Interface DefaultLocale

@Retention(RUNTIME) @Target({METHOD,TYPE}) @Inherited @API(status=STABLE, since="6.1") @ExtendWith(org.junit.jupiter.api.util.DefaultLocaleExtension.class) public @interface DefaultLocale
@DefaultLocale is a JUnit Jupiter extension for changing the value returned by Locale.getDefault() for a test execution.

The Locale to set as the default locale can be configured in several ways:

  • using a language tag
  • using a Locale.Builder together with
    • a language
    • a language and a county
    • a language, a county, and a variant

Please keep in mind that the Locale.Builder does a syntax check, if you use a variant. The given string must match the BCP 47 (or more detailed RFC 5646) syntax.

If a language tag is set, none of the other fields must be set. Otherwise, an ExtensionConfigurationException will be thrown. Specifying a country() but no language(), or a variant() but no country() and language() will also cause an ExtensionConfigurationException. After the annotated element has been executed, the default Locale will be restored to its original value.

@DefaultLocale can be used on the method and on the class level. It is inherited from higher-level containers, but can only be used once per method or class. If a class is annotated, the configured Locale will be the default Locale for all tests inside that class. Any method level configurations will override the class level default Locale.

During parallel test execution, all tests annotated with @DefaultLocale, @ReadsDefaultLocale, and WritesDefaultLocale are scheduled in a way that guarantees correctness under mutation of shared global state.

For more details and examples, see the User Guide.

Since:
6.1
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    country
    An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code.
    String
    language
    An ISO 639 alpha-2 or alpha-3 language code, or a language subtag up to 8 characters in length.
    Class<? extends LocaleProvider>
    localeProvider
    A class implementing LocaleProvider to be used for custom Locale resolution.
    String
    value
    A language tag string as specified by IETF BCP 47.
    String
    variant
    An IETF BCP 47 language string that matches the RFC 5646 syntax.

  • Element Details

    • value

      String value
      A language tag string as specified by IETF BCP 47. See Locale.forLanguageTag(String) for more information about valid language tag values.
      Default:
      ""

    • language

      String language
      An ISO 639 alpha-2 or alpha-3 language code, or a language subtag up to 8 characters in length. See the Locale class description about valid language values.
      Default:
      ""

    • country

      String country
      An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code. See the Locale class description about valid country values.
      Default:
      ""

    • variant

      String variant
      An IETF BCP 47 language string that matches the RFC 5646 syntax. It's validated by the Locale.Builder, using sun.util.locale.LanguageTag#isVariant.
      Default:
      ""

    • localeProvider

      Class<? extends LocaleProvider> localeProvider
      A class implementing LocaleProvider to be used for custom Locale resolution. This is mutually exclusive with other properties, if any other property is given a value it will result in an ExtensionConfigurationException.
      Default:
      org.junit.jupiter.api.util.NullLocaleProvider.class