Welcome to Arjuna - The Framework for Professional Coded Testing

Arjuna is a Python based test automation framework developed by Rahul Verma.

It is an open source, Apache Licensed software: Arjuna on GitHub.

Rahul has implemented smaller variants of features in Arjuna across frameworks and organizations, or given advice around it. However Arjuna being a generic library has the most complete implementation of his ideas, away from project specific contexts and constraints.

For test execution, Arjuna is implemented as a pytest plugin and provides its own markup over pytest as its underlying test engine. If you like, you can make use of Arjuna with any other test engine or custom frameworks as well.

You’d need Python 3.8+ to make use of Arjuna.

Note: On Linux, the built-in Python3 build has issues with the Python’s built-in enum module which is heavily used in Arjuna. One alternative is to install ActiveState Python on linux. Advanced users can go for installing a custom Python build.

You can find a lot of example code for using Arjuna in Arjex project on GitHub.

Tester’s Guide

Arjuna Fundamentals

• Installing Arjuna
• Arjuna Test Project
  • Creating a New Test Project using create-project Command
  • Purpose of Different Directories and Files
• Basics of Writing Automated Tests in Arjuna
  • Tests are Test Functions
  • Basic Usage of @test Decorator
  • Running a Specific Test Function
• Provisions in @test Decorator
  • Skipping a Test
  • Handling Expected Failures in Tests
  • Specifying Built-in Test Attributes
  • User-Defined Test Attributes
  • Specifying Tags, Bugs, Environments
• Arjuna’s Command Line Interface as pytest plugin
  • -h or –help
  • Specifying Test Project
  • Controlling Test Selection
  • Controlling Test Reporting
  • Performing a Dry Run
  • Specifying Reference Configuration
  • Providing Arjuna Options and/or User Defined Options
  • Controlling Logging Level
  • Linking Other Arjuna Test Projects to Your Project
• Handling Test Resources
  • What are Test Resources?
  • Resource Levels - @for_group, @for_module, @for_test
  • Module-Specific Resources
  • Cross-Module Shared Resources
  • Data-Driven Test Resources
  • Associating a Resource with a Test
  • Setting a Resource as a Default
• Handling Configuration Options
  • Understanding Configuration System of Arjuna
  • project.yaml - Setting Project Level Configuration Options
  • Configuration Builder - Creating Custom Configurations
  • Defining and Handling User Options
  • Configuration Builder - Adding options from a .yaml File
  • The Magic C Function
  • Data Configurations and Environment Configurations
  • Arjuna Options Reference for Overriding
• Test Selection Rules
  • Purpose
  • Inclusion vs Exclusion Rules
  • Rules Grammar
  • Using Custom Test Selection Rules
  • Shortcut Rules for Test Package, Module and Function Names
  • Rule Evaluation Sequence
• Logging
  • Introduction
  • Arjuna’s Logging Functions to Support Python Logging Levels
  • Controlling Which Log Messages Are Included on Console and in Log File
  • Default Logging Levels
  • Arjuna’s TRACE Log Level
  • Overriding Logging Level Defaults
  • Contextual Logging
  • Auto-Logging using @track Decorator
  • Tracking Methods, Functions, Properties
  • Tracking All Methods in a Class
  • Default Logging Level for @track
  • Changing Logging Level for @track
• Test Reporting
  • Introduction
  • HTML and JUnit-Style XML Reporting
  • Report Directory Structure
  • Report File Names
  • Choosing Report Format(s)
  • Logging in the context of Reporting
  • Reporting Protocols
  • Where is the reporting entry for Resource Tear Down?

Handling Data and Files in Arjuna

• Data Driven Testing with Arjuna
  • Purpose
  • Single data record
  • Multiple Data Records
  • Driving with Static Data Function
  • Driving with Static Data Generator
  • Driving with Dynamic Data Function or Generator
  • Driving with Static Data Classes
  • Driving with Dynamic Data Classes
  • Driving with Data Files
  • Driving with Multiple Data Sources
• Data Spaces - Shareable Data Objects for Tests
  • Need for Spaces in Test Automation
  • Types of Spaces
  • Defining and Utilizing Objects in Spaces
• Data References
  • Purpose
  • Contextual Data References
  • Indexed Data References
  • Retrieving Complete Referred Object
  • Retrieving Complete Contextual/Indexed Data Reference
  • Contextual Data References Behave Like Python Dicts
  • Indexed Data References Behave Like Python Tuples (Sequences)
• Data Generation and Data Entities
  • Random Data Generation
  • Creating a Basic Data Entity
  • Setting Defaults in Data Entity
  • Basic Usage of Random with Data Entity
  • Dynamic Generation of Data for Data Entities
  • Processing Dynamically Generated Data
  • Defining Composite Data Using composite and composer Constructs
  • Creating a Data Entity from Other Data Entities
• Parsing Text, JSON, YAML, XML, HTML Files and Strings
  • Introduction
  • Text
  • JSON (Javascript Object Notation)
  • YAML
  • XML
  • HTML
• Data Localisation
  • Purpose
  • Locale Enum
  • Excel based Localization
  • JSON Based Localization
  • Strict vs Non-strict Mode for Localization

Web GUI Automation

• The GuiApp class
  • Launching a Web Application
  • Associating a App with a Base URL
  • Setting GuiApp Base URL in Configuration
• Element Identification and Interaction
  • GuiElement and Widgets
  • Identification
  • Interaction with GuiElement
• Gui Namespace - Externalizing Locators
  • The GNS File
  • Associating GNS File with GuiApp
  • Using GNS Labels in Code
  • GuiApp GNS as Fallback GNS for Pages, Sections and Widgets
• GuiWidget Locators
  • Basic Locators
  • Arjuna’s Locator Extensions
• Alternative Locators - Specifying Multiple Locators with OR Relationship
  • Using Different Locator Types
  • Using Same Locator Type
• Dynamic/Formatted GuiWidget Locators
  • Arjuna’s $<name>$ Placeholder
  • Auto-Formatting using C,L,R Magic Functions
  • Formatting Placeholders using formatter Method
• Gui Widget Meta Data - Controlling Selection and Interaction Behavior
  • Specifying Visual Relationships with Other GuiElements
  • Selection-Time Position (pos) Based Filtering
• Defining Your Own Locators using withx
  • Global Locators in The withx.yaml File
  • Defining and Using a New Locator with Anonymous/Positional Placeholders ($$)
  • Defining and Using a New Locator with Named Placeholders ($<name>$)
  • Defining New Locator Locally for a given Gui
  • Mixing Anonymous/Positional ($$) and Named ($<name>$) Placeholders
• Gui Widgets
  • GuiElement
  • GuiMultiElement - Handling Multiple GuiElements Together
  • DropDown - Handling Default HTML Select
  • RadioGroup - Handling Default HTML Radio Group
• Advanced Gui Abstractions
  • Concept of Gui in Arjuna
  • Gui Abstraction Models
  • Arjuna’s Gui Loading Model

HTTP Automation

• Introduction
• The Http Facade Class
• Supported HTTP Methods
• Handling Content Types
• Creating an HTTP Session
• Setting a Request Label
• Setting Arbitrary Query String Parmaters in URL
• Checking Expected HTTP Status Code(s)
  • Inquiring
  • Asserting
  • xcodes Argument
  • xcodes Argument in strict Mode
• The HttpResponse Object
  • Basic Data Extraction
  • Redirections
  • Handling Response Content
• Support for Open Authentication (OAuth)
  • OAuth Client Grant Session
  • OAuth Implicit Grant Session
  • Creating a New Session from an OAuth Session

Notes About Python Libraries and Tools Used in Arjuna

• Introduction
• Beware of the Boolean Interpretation in YAML

Frequently Asked Questions (FAQs)

• Introduction
• Can I Make an Arjuna Test Project depend on another Arjuna Test Project?
• Can I Maintain Local Configuration (.local) Files That Override the Default Configuration Files?

Tester Programming Interface (TPI) Reference

All classes, functions, enums and exceptions that are supposed to be directly used by a test author are a part of Arjuna’s Tester Programming Interface (TPI).

This interface is fully encapsulated in arjuna.tpi package.

You can either do a fully qualified import for a public name, for example:

from arjuna.tpi.log import log_info

or an easy, simple import that imports all public TPI names from Arjuna:

from arjuna import *

Following links direct you to documentation for all public names:

Test, Test Resources and Assertions

• @test

  • skip
  • xfail
  • problem_in

• Assertions

  • Asserter
  • AsserterMixIn
  • IterableAsserterMixin

• Test Resources

  • @for_test
  • @for_module
  • @for_group

Test Configuration

• ArjunaOption Enum
• Configuration
• ConfigBuilder

The Magic Functions

• The Magic C Function
• The Magic L Function
• The Magic R Function

Data Driven Testing

• Data Source Markup

  • record
  • records
  • data_function
  • data_class
  • data_file
  • many_data_sources

• DataRecord

Data Generation and Data Entities

• Random
• generator
• composite
• composer
• data_entity

Data References

• IndexedDataReference
• ContextualDataReference

Web GUI Automation

• Gui: It represents all type of Guis and is the base class for the following classes:

  • GuiApp

  • GuiAppContent: It represents the content of a GuiApp and is the base class of the following classes:

    • GuiPage
    • GuiSection
    • GuiDialog

• Defining and formatting Gui Widget Locators:

  • GuiWidgetDefinition

  • Classes related to formatting of GuiWidgetDefinition:

    • GNSLabelFormatter
    • GuiWidgetDefinitionFormatter

• Different Gui Widgets

  • GuiElement

  • GuiMultiElement

    • Filtering a GuiMultiElement - GuiMultiElementFilter

  • GuiDropDown
  • GuiRadioGroup

• Inquiring Gui Source

  • GuiPageSource
  • GuiElementSource
  • GuiMultiElementSource
  • GuiSourceContent - Encapsulates source content for all Guis and GuiWidgets.

HTTP Automation

• Http
• HttpSession
• HttpRequest
• HttpResponse

• OAuth Support

  • OAuthSession
  • OAuthClientGrantSession
  • OAuthImplicitGrantSession

Reporting Protocols

• ScreenShooter
• NetworkRecorder

Objects In Arjuna Hooks

• Configurator

Parsers

• Text

  • Text
  • TextFile
  • TextFileAsLines
  • DelimTextFileWithLineAsSeq
  • DelimTextFileWithLineAsMap

• JSON

  • Json
  • JsonElement
  • JsonDict
  • JsonList
  • JsonSchema
  • JsonSchemaBuilder

• YAML

  • Yaml
  • YamlElement
  • YamlDict
  • YamlList

• XML

  • Xml
  • XmlNode
  • NodeLocator

• HTML

  • Html
  • HtmlNode

Helpers

• HardCoded.sleep
• Image

• Date Time Helper Classes

  • Time
  • DateTime
  • DateTimeDelta
  • DateTimeDeltaBuilder
  • DateTimeStepper

• Arjuna Types

  • CIStringDict
  • ProcessedKeyDict
  • OnceOnlyKeyCIStringDict
  • Point
  • Offset
  • Screen
  • nvpair
  • nvpairs
  • withx
  • attr

• Position Based Extractors

Logging

• Log

  • log_trace
  • log_debug
  • log_info
  • log_warning
  • log_error
  • log_fatal

• @track

Arjuna Exceptions

• Tests

  • TestDecoratorError
  • TestSelectorNotFoundError

• Configuration

  • UndefinedConfigError
  • ConfigCreationError
  • DisallowedArjunaOptionError
  • ArjunaOptionValidationError

• Test Session, Stage and Group

  • TestSessionsFileNotFoundError
  • UndefinedTestSessionError
  • InvalidTestSessionDefError
  • TestStagesFileNotFoundError
  • UndefinedTestStageError
  • InvalidTestStageDefError
  • TestGroupsFileNotFoundError
  • UndefinedTestGroupError

• Gui Automation

  • GuiWidgetDefinitionError
  • GuiWidgetForLabelPresentError
  • GuiWidgetPresentError
  • GuiWidgetForLabelNotPresentError
  • GuiWidgetNotPresentError
  • GuiNamespaceLoadingError
  • GuiNotLoadedError
  • GuiLabelNotPresentError

• HTTP Automation

  • HttpRequestCreationError
  • HttpConnectError
  • HttpSendError
  • HttpUnexpectedStatusCodeError

Indices and tables

• Index
• Module Index
• Search Page

Contributors

This package is authored and maintained by:

Rahul Verma (@rahul_verma)

with the help of patches submitted by these contributors.

Copyright and License

Copyright 2015-2020 Rahul Verma

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.