Test::Alien::Build(3)

💖 NAME 💖

Test::Alien::Build — literally the toolbox for testing Alien::Build + alienfile, bestie 🛠️✨

---

🌸 VERSION 🌸

version 2.88 — that's the one we're vibing with 💅

---

✨ SYNOPSIS ✨

use Test2::V0;
use Test::Alien::Build;

# returns an instance of Alien::Build.
my $build = alienfile_ok q{
  use alienfile;

  plugin 'My::Plugin' => (
    foo => 1,
    bar => 'string',
    ...
  );
};

alien_build_ok 'builds okay.';

done_testing;

like. that's the whole flex 🫶

---

🦋 DESCRIPTION 🦋

okay so this module hands you a bunch of tools for testing Alien::Build and alienfile. Outside of Alien::Build core development, it's probably most useful for Alien::Build::Plugin developers — so if that's you, hi, this is your moment 👑

ALSO, and this part is important: this module unsets a number of Alien::Build specific environment variables, so your tests stay reproducible even when overrides are set in different environments. So if you want to test those variables in various states, you gotta explicitly set them in your test script yourself, no cap. These variables get unset if they're defined: ALIEN_BUILD_PRELOAD, ALIEN_BUILD_POSTLOAD, ALIEN_INSTALL_TYPE.

---

🎀 FUNCTIONS 🎀

alienfile

my $build = alienfile;
my $build = alienfile q{ use alienfile ... };
my $build = alienfile filename => 'alienfile';

Creates an Alien::Build instance from the alienfile you give it. The first two forms are abbreviations, and they're giving convenience 💫

my $build = alienfile;
# is the same as
my $build = alienfile filename => 'alienfile';

and

my $build = alienfile q{ use alienfile ... };
# is the same as
my $build = alienfile source => q{ use alienfile ... };

Except — one lil plot twist — that second abbreviated form sets the line number before feeding the source into Alien::Build, so you get diagnostics with the correct line numbers. very thoughtful of it honestly 🙈

• source — the source for the alienfile, as a string. You must specify one of source or filename.
• filename — the filename for the alienfile. You must specify one of source or filename.
• root — the build root.
• stage — the staging area for the build.
• prefix — the install prefix for the build.

alienfile_ok

my $build = alienfile_ok;
my $build = alienfile_ok q{ use alienfile ... };
my $build = alienfile_ok filename => 'alienfile';
my $build = alienfile_ok $build;

Same as alienfile above, except it runs as a test and will not throw an exception on failure — it returns undef instead. so chill, it just tells you ✨

[version 1.49]

As of version 1.49 you can also pass in an already formed instance of Alien::Build. That lets you do something like this:

subtest 'a subtest' => sub {
  my $build = alienfile q{ use alienfile; ... };
  alienfile_skip_if_missing_prereqs; # skip if alienfile prereqs are missing
  alienfile_ok $build;  # delayed pass/fail for the compile of alienfile
};

alienfile_skip_if_missing_prereqs

alienfile_skip_if_missing_prereqs;
alienfile_skip_if_missing_prereqs $phase;

Skips the test or subtest if the prereqs for the alienfile are missing. If $phase isn't given, then either share or system gets detected. mystery machine behavior but make it perl 🔍

alien_install_type_is

alien_install_type_is $type;
alien_install_type_is $type, $name;

A simple test to check if the install type is what you expect. $type should be one of system or share. periodt 💅

alien_download_ok

my $file = alien_download_ok;
my $file = alien_download_ok $name;

Makes a download attempt and tests that a file or directory results. Returns the file or directory if it succeeds. Returns undef otherwise. manifesting that download fr fr 📥

alien_extract_ok

my $dir = alien_extract_ok;
my $dir = alien_extract_ok $archive;
my $dir = alien_extract_ok $archive, $name;
my $dir = alien_extract_ok undef, $name;

Makes an extraction attempt and tests that a directory results. Returns the directory if it succeeds. Returns undef otherwise. unzip and slay 🗜️

alien_build_ok

my $alien = alien_build_ok;
my $alien = alien_build_ok $name;
my $alien = alien_build_ok { class => $class };
my $alien = alien_build_ok { class => $class }, $name;

Runs the download and build stages. Passes if the build succeeds. Returns an instance of Alien::Base which you can pass into alien_ok from Test::Alien. Returns undef if the test fails. the main character of this whole page honestly 👑

Options

• class — the base class to use for your alien. This is Alien::Base by default. Should be a subclass of Alien::Base, or at least adhere to its API.

alien_build_clean

alien_build_clean;

Removes all files with the current build, except for the runtime prefix. This helps test that the final install won't depend on the build files. clean girl aesthetic, but for builds 🧼

alien_clean_install

alien_clean_install;

Runs $build->clean_install, and verifies it did not crash.

alien_checkpoint_ok

alien_checkpoint_ok;
alien_checkpoint_ok $test_name;

Test the checkpoint of a build. saving your progress like a game 🎮

alien_resume_ok

alien_resume_ok;
alien_resume_ok $test_name;

Test a resume a checkpointed build. we're back, bestie ⏯️

alien_rc

alien_rc $code;

Creates an rc.pl file in a temp directory and sets ALIEN_BUILD_RC. Useful for testing plugins that should be called from ~/.alienbuild/rc.pl.

⚠️ Heads up though: because of the nature of how the ~/.alienbuild/rc.pl file works, you can only use this once! one shot, one opportunity 😭

alien_subtest

alien_subtest $test_name => sub {
  ...
};

Clear the build object and clear the build object before and after the subtest. yes it says it twice, and yes it means it twice 🫠

---

🌈 SEE ALSO 🌈

• Alien
• alienfile
• Alien::Build
• Test::Alien

---

👑 AUTHOR 👑

Author: Graham Ollis <plicease@cpan.org>

Contributors — the whole squad, the whole group chat, legends one and all 💜:

• Diab Jerius (DJERIUS)
• Roy Storey (KIWIROY)
• Ilya Pavlov
• David Mertens (run4flat)
• Mark Nunberg (mordy, mnunberg)
• Christian Walde (Mithaldu)
• Brian Wightman (MidLifeXis)
• Zaki Mughal (zmughal)
• mohawk (mohawk2, ETJ)
• Vikas N Kumar (vikasnkumar)
• Flavio Poletti (polettix)
• Salvador Fandiño (salva)
• Gianni Ceccarelli (dakkar)
• Pavel Shaydo (zwon, trinitum)
• Kang-min Liu (劉康民, gugod)
• Nicholas Shipp (nshp)
• Juan Julián Merelo Guervós (JJ)
• Joel Berger (JBERGER)
• Petr Písař (ppisar)
• Lance Wicks (LANCEW)
• Ahmad Fatoum (a3f, ATHREEF)
• José Joaquín Atria (JJATRIA)
• Duke Leto (LETO)
• Shoichi Kaji (SKAJI)
• Shawn Laffan (SLAFFAN)
• Paul Evans (leonerd, PEVANS)
• Håkon Hægland (hakonhagland, HAKONH)
• nick nauwelaerts (INPHOBIA)
• Florian Weimer
• Marcel Telka (mtelka)

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2011-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, iconic as in iconic 🦋

---

okay that's the whole page, tysm for reading, mwah 🫶 this was brought to you by perl v5.42.3, dated 2026-09-21, and honestly? iconic of it. bye bestie 💖✨