Get Started with Test Junkie: Install and Run a Suite

01

Installation

In order to install Test Junkie you need to have Python installed. Test Junkie supports Python 3.9 through the latest stable release (see the CI test matrix for the exact current list).

Install from PyPI

From your terminal: pip install test-junkie or python -m pip install test-junkie
You are done and ready to go!

To upgrade: pip install test-junkie --upgrade

To uninstall: pip uninstall test-junkie

02

Test Definition

Lets get you started with some initial test definitions. Save code bellow into a local Python file. Lets say C:\Development\MyTests\demo.py.

demo.pypython

from test_junkie.decorators import Suite, beforeTest, afterTest, test, beforeClass, afterClass

@Suite()
class ExampleTestSuite:

    @beforeClass()
    def before_class(self):
        print("Hi, I'm optional before class")

    @beforeTest()
    def before_test(self):
        print("Hi, I'm optional before test")

    @afterTest()
    def after_test(self):
        print("Hi, I'm optional after test")

    @afterClass()
    def after_class(self):
        print("Hi, I'm optional after class")

    @test()
    def something_to_test1(self):
        print("Hi, I'm test #1")

    @test()
    def something_to_test2(self):
        print("Hi, I'm test #2")

    @test()
    def something_to_test3(self):
        print("Hi, I'm test #3")

03

Test Execution

There are two possible ways to run tests on Test Junkie. Both are fully configurable!

Programmatically - allows to invoke the tests anywhere in your code
Test Junkie CLI - allows to run tests without any additional code required

Gives you flexibility to build a wrapper around Test Junkie to support use cases it may not support out of the box.

demo.pypython

if "__main__" == __name__:
    from test_junkie.runner import Runner
    runner = Runner([ExampleTestSuite])
    runner.run()

> python demo.py

Test Junkie 0.9a6 · Python 3.12.5 · Windows 11
  tests    1 suite, 3 tests
  mode     sequential

ExampleTestSuite  demo.py  [||||||||||||||||||||||||]  3/3  0.00s

Total                      [||||||||||||||||||||||||]  3/3  100%  0.0s

Summary ────────────────────────────────────────────────────────────────────────

  Suite               Pass  Fail  Error  Ignore  Skip  Cancel     Time
  ExampleTestSuite       3     ·      ·       ·     ·       ·    0.00s
  ────────────────────────────────────────────────────────────────────
  Total                  3     ·      ·       ·     ·       ·    0.01s
  3 tests             100%                                   

────────────────────────────────────────────────────────────────────────────────

 PASSED

The runner object gives you access to test metrics after the run. See JSON report for more info, and Running tests in the documentation for every way to filter and run.

PYTHONPATH

If your suites import your project's own code (page objects, helpers), the project root must be importable. Add it to PYTHONPATH, or run python -m test_junkie run ... from the project root. Suites that only import installed packages need neither. tj run --guess-root can also find the root for you.

Test Junkie CLI is installed by default. Access it via tj from your terminal — tell it where your tests are and it handles the rest.

> tj run -s "C:\Development\MyTests\demo.py"

Test Junkie 0.9a6 · Python 3.12.5 · Windows 11
  tests    C:\Development\MyTests\demo.py · 1 suite, 3 tests · found in 0.00s
  mode     sequential

ExampleTestSuite  demo.py  [||||||||||||||||||||||||]  3/3  0.00s

Total                      [||||||||||||||||||||||||]  3/3  100%  0.0s

Summary ────────────────────────────────────────────────────────────────────────

  Suite               Pass  Fail  Error  Ignore  Skip  Cancel     Time
  ExampleTestSuite       3     ·      ·       ·     ·       ·    0.00s
  ────────────────────────────────────────────────────────────────────
  Total                  3     ·      ·       ·     ·       ·    0.00s
  3 tests             100%                                   

────────────────────────────────────────────────────────────────────────────────

 PASSED   exit code 0

Quality of Life — Save your config

Typing out -s, -S, -T, and other flags on every run gets old fast. tj config update persists any flag to a config file so subsequent tj run calls pick them up automatically — no arguments needed. You only need to set it once, and any flag you pass directly at runtime still takes precedence over what's saved.

For example, save your test source path once. Test Junkie confirms what it saved, with the old and new value and the command that undoes it. From then on a plain tj run picks the setting up, no flags needed, and its header shows that a saved config was used, where it is, and what it set:

> tj config update -s "C:\Development\MyTests\demo.py"

 SAVED   1 setting · C:\Users\you\AppData\Local\Test-Junkie\Test-Junkie\.tj.cfg
  sources                       ·  →  C:\Development\MyTests\demo.py

  Undo: tj config restore -s

> tj run

Test Junkie 0.9a6 · Python 3.12.5 · Windows 11
  tests    C:\Development\MyTests\demo.py · 1 suite, 3 tests · found in 0.00s
  mode     sequential
  config   C:\Users\you\AppData\Local\Test-Junkie\Test-Junkie\.tj.cfg
           sources C:\Development\MyTests\demo.py

…

To see everything you've saved, tj config show --all lists every setting, grouped by what it controls. Saved values are bold; the rest show their default:

> tj config show --all

Config  C:\Users\you\AppData\Local\Test-Junkie\Test-Junkie\.tj.cfg

Discovery
  sources                       C:\Development\MyTests\demo.py
  guess_root                    ·  default off

Parallel and retries
  test_multithreading_limit     ·  default 1
  suite_multithreading_limit    ·  default 1
  retry                         ·
  no_retry                      ·  default off
  retry_policy                  ·

Limits
  suite_throttling              ·  default 0
  test_throttling               ·  default 0
  ramp_up                       ·  default 0
  traceback_limit               ·  default 3000
  message_limit                 ·  default 3000
  truncate                      ·  default middle

Filters
  tests                         ·
  features                      ·
  components                    ·
  owners                        ·
  run_on_match_any              ·
  run_on_match_all              ·
  skip_on_match_any             ·
  skip_on_match_all             ·

Reports and output
  html_report                   ·
  xml_report                    ·
  json_report                   ·
  monitor_resources             ·  default off
  code_cov                      ·  default off
  cov_rcfile                    ·
  quiet                         ·  default off
  per_test                      ·  default off
  no_capture                    ·  default off
  flag_flaky                    ·  default off
  fail_on_flaky                 ·  default off

────────────────────────────────────────────────────────────────────────────────

1 of 32 settings saved · tj config update -h to change one, tj config restore -h to clear one

Go to the tj config documentation for the full reference.

{# Live-demo card: thumbnail of the HTML report + label, title, text, button. Styles: .demo-cta in static_src/components.css. with: text="…" (required), compact=True for a smaller thumbnail (Get Started), title="…" (default "Click through a real report"). #}

Test Junkie HTML report: summary stats, CPU and memory chart, and a test's detail panel showing its metadata and two attempts

Live demo

Curious what a finished run looks like?

A real HTML report from a 0.9a8 run, as Test Junkie writes it: results by suite and test, retries, metadata and timings.

Open the live demo →

Get Started

Installation

Install from PyPI

Install from source

Test Definition

Test Execution

Quality of Life — Save your config