CONTENTS

• NAME
• DESCRIPTION
• THINGS THAT BREAK
  • Test::Builder1.5/2 conditionals
    • The Problem
    • The Fix
  • Replacing the Test::Builder singleton
    • The Problem
    • The Fix
  • Directly Accessing Hash Elements
    • The Problem
    • The Fix
  • Subtest indentation
    • The Problem
    • The Fix
• DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED
  • WORKS BUT TESTS WILL FAIL
  • UPGRADE SUGGESTED
  • NEED TO UPGRADE
  • STILL BROKEN
• MAKE ASSERTIONS -> SEND EVENTS
  • LEGACY
  • TEST2
• WRAP EXISTING TOOLS
  • LEGACY
  • TEST2
• USING UTF8
  • LEGACY
  • TEST2
• AUTHORS, CONTRIBUTORS AND REVIEWERS
• SOURCE
• MAINTAINER
• COPYRIGHT

#NAME

Test2::Transition - Transition notes when upgrading to Test2

#DESCRIPTION

This is where gotchas and breakages related to the Test2 upgrade are documented. The upgrade causes Test::Builder to defer to Test2 under the hood. This transition is mostly transparent, but there are a few cases that can trip you up.

#THINGS THAT BREAK

This is the list of scenarios that break with the new internals.

#Test::Builder1.5/2 conditionals

#The Problem

a few years back there were two attempts to upgrade/replace Test::Builder. Confusingly these were called Test::Builder2 and Test::Builder1.5, in that order. Many people put conditionals in their code to check the Test::Builder version number and adapt their code accordingly.

The Test::Builder2/1.5 projects both died out. Now the conditional code people added has become a mine field. A vast majority of modules broken by Test2 fall into this category.

#The Fix

The fix is to remove all Test::Builder1.5/2 related code. Either use the legacy Test::Builder API, or use Test2 directly.

#Replacing the Test::Builder singleton

#The Problem

Some test modules would replace the Test::Builder singleton instance with their own instance or subclass. This was usually done to intercept or modify results as they happened.

The Test::Builder singleton is now a simple compatibility wrapper around Test2. The Test::Builder singleton is no longer the central place for results. Many results bypass the Test::Builder singleton completely, which breaks and behavior intended when replacing the singleton.

#The Fix

If you simply want to intercept all results instead of letting them go to TAP, you should look at the Test2::API docs and read about pushing a new hub onto the hub stack. Replacing the hub temporarily is now the correct way to intercept results.

If your goal is purely monitoring of events use the Test2::Hub->listen() method exported by Test::More to watch events as they are fired. If you wish to modify results before they go to TAP look at the Test2::Hub->filter() method.

#Directly Accessing Hash Elements

#The Problem

Some modules look directly at hash keys on the Test::Builder singleton. The problem here is that the Test::Builder singleton no longer holds anything important.

#