Developer Interface¶

Main API¶

All the methods you will need for general usage.

gaunit.check_har(test_case_id: str, tracking_plan: gaunit.models.TrackingPlan, har=None, har_path=None) → gaunit.models.Result¶

Performs checks of a har dict or HAR JSON file against a TrackingPlan.

Example

>>> expected_events = [{"t":"pageview","dt":"home"},...]
>>> tracking_plan = gaunit.TrackingPlan.from_events("my_test_case", expected_events)
>>> r = gaunit.check_har("my_test_case", tracking_plan, har=har) # from har dict
>>> r.was_sucessful()
True
>>> r = gaunit.check_har("my_test_case", tracking_plan, har_path="har.json") # from HAR file
>>> r.was_sucessful()
True

Parameters

test_case_id (str) – test case id (same id used to match with tracking plan)
tracking_plan (TrackingPlan) – tracking plan containing expected events for this test case. Defaults to None
har (dict) – actual har for this test case in dict format. Defaults to None
har_path (str) – path to HAR file for this test case (standard HAR JSON). Defaults to None

Note

One and one only argument must be given: har or har_path

Returns: complete results of your test case.
Return type: gaunit.Result

gaunit.check_perf_log(test_case_id: str, tracking_plan: gaunit.models.TrackingPlan, perf_log: list) → gaunit.models.Result¶

Performs checks of a Performance log against a TrackingPlan.

Warning

Performance logs do not record POST requests (massively used with GA4 and soon, according to Google, with gtag.js). This method will be deprecated in future versions. We advise you to use gaunit.check_har() instead

Example

See full example on Github here.

Parameters

test_case_id (str) – test case id (same id used to match with tracking plan)
tracking_plan (TrackingPlan) – tracking plan containing expected events for this test case. Defaults to None
perf_log (list) – log entries from driver

Returns

complete results of your test case.

Return type

gaunit.Result

Classes¶

class gaunit.TrackingPlan¶

User-defined class object representing a TrackingPlan.

Used as an input to perform a check or create a TestCase.

Example

See Documentation Getting Started or How Tos for more details.

get_expected_events(test_case_id: str) → list¶

Get expected events for a given test case.

Parameters: test_case_id (str) – test case id
Raises: gaunit.TrackingPlanError – if test case is not found in tracking plan

classmethod from_events(test_case_id: str, expected_events: List[dict]) → gaunit.models.TrackingPlan¶

Creates an instance of TrackingPlan from a list of expected events (only for one test case)

Example :

>>> from gaunit import TrackingPlan
>>> expected_events = [{"t":"pageview","dt":"home"},...]
>>> tracking_plan = TrackingPlan.from_events("my_test_case", expected_events)

Parameters

test_case_id (str) – test case id
expected_events (list[Dict]) – expected events for this tests case

Returns

TrackingPlan instance

classmethod from_json(path: str) → gaunit.models.TrackingPlan¶

Creates an instance of TrackingPlan from a JSON file

See Documentation for the JSON file format.

Example

>>> from gaunit import TrackingPlan
>>> tracking_plan = TrackingPlan.from_json("tracking_plan.json")

Parameters: path (str) – path to JSON file representing the tracking plan
Raises: gaunit.TrackingPlanError – if tracking plan format is not valid
Returns: TrackingPlan instance.

classmethod from_spreadsheet(sheet: gspread.models.Spreadsheet) → gaunit.models.TrackingPlan¶

Creates an instance of TrackingPlan from a Google Spreadsheet.

This method uses gspread to connect to Google Sheets and import test cases and expected events. See Documentation for the spreadsheet format.

Examples

>>> import gspread
>>> from gaunit import TrackingPlan
>>> gc = gspread.service_account()  # authentication
>>> sh = gc.open("Example spreadsheet")  # open spreadsheet
>>> tp = TrackingPlan.from_spreadsheet(sh)  # import tracking plan

Parameters: sheet (gspread.Spreadsheet) – gspread instance of the spreadsheet to import
Returns: TrackingPlan instance.

to_json(file: str)¶

Exports TrackingPlan instance into a JSON file.

Example

>>> from gaunit import TrackingPlan
>>> expected_events = [{"t":"pageview","dt":"home"},...]
>>> tracking_plan = gaunit.TrackingPlan.from_events("my_test_case", expected_events)
>>> tracking_plan.to_json("tracking_plan.json")

Parameters: file (str) – target file

add_test_case(test_case_id: str, expected_events: List[dict])¶

Add or update expected events for a given test case.

Example

>>> from gaunit import TrackingPlan
>>> expected_events = [{"t":"pageview","dt":"home"},...]
>>> tracking_plan = TrackingPlan()
>>> tracking_plan.add_test_case("my_test_case", expected_events)

See also

gaunit.check_har() is more straight forward to use.

id¶

Test case id (same id used to match with tracking plan)

Type: str

tracking_plan¶

Tracking plan containing expected events for this test case. Defaults to None

Type: TrackingPlan

har¶

Actual har for this test case in dict format. Defaults to None

Type: dict

har_path¶

Path to HAR file for this test case (standard HAR JSON). Defaults to None.

Type: str

perf_log¶

Browser performance log

Type: list

actual_events¶

List of GA events params parsed from HAR or http log Each event is represented by a dict of params (same as expected_events). Example: [{"t":"pageview","dt":"home"},...]

Type: list

load_har(har=None, har_path=None)¶

Extracts and stores analytics events from a har.

Updates actual_events. Takes one and one only argument : dict or path to a json file

Parameters

har (dict, optional) – [description]. Defaults to None.
har_path (str, optional) – [description]. Defaults to None.

load_perf_log(perf_log: list)¶

Extracts and stores analytics events from Performance Log.

For more info on Performance Log, see https://chromedriver.chromium.org/logging/performance-log

Warning

Performance logs do not record POST requests (massively used with GA4 and soon, according to Google, with gtag.js). This method will be deprecated in future versions. We advise you to use gaunit.check_har() or TestCase.load_har() instead.

Parameters: perf_log (list) – log entries from driver.get_log("performance")

check(ordered=True) → Tuple[list, list]¶

Compares events from tracking plan and from log and returns 2 checklists.

Compares expected_events and actual_events, which makes sense!

Parameters: ordered (bool, optional) – True if we want hits to respect tracking plan order (default behavior)
Raises: gaunit.TestCaseCheckError – if no valid HAR or Perf log were provided before check
Returns: 2 checklists; First checklist tells which event in tracking plan is missing. Second checklist tells which analytics event from test case corresponds to an expected event.
Return type: Tuple[list, list]

result()¶: Performs tracking checks and return a Result instance

class gaunit.Result(test_case: gaunit.models.TestCase, checklist_expected: list, checklist_actual: list)¶

Let you store, get or print results from a test case in various forms

Usually, Result will be returned by main API methods or TestCase.result() .

See also :: gaunit.check_har(), TestCase.result()

expected_events¶

Events from tracking plan

Type: list

actual_events¶

Events found during test run

Type: list

checklist_expected_events¶

Checklist of events from tracking plan which are missing (False if missing)

Type: list

checklist_actual_events¶

Checklist of events found in log which corresponds to an expected event

Type: list

was_successful() → bool¶

returns the result of test case

Returns: True if test case was successful
Return type: bool

get_status_expected_events() → list¶

Returns expected event and their status

Returns: list of expected events and their status (True if found in actual events))
Return type: list

Example

>>> from gaunit import TestCase
>>> r = gaunit.check_har("my_test_case", tracking_plan, har=har)
>>> r.get_status_expected_events()
[{'event':{'t':'pageview', 'dp': 'home'}, 'found': True},..]

get_status_actual_events() → list¶

Returns actual events and which ones were expected in tracking plan

Returns: list of actual hits
Return type: list

Example

>>> from gaunit import TestCase
>>> r = gaunit.check_har("my_test_case", "tracking_plan.json", har=har)
>>> r.get_status_actual_events()
[{'event:{'t':'pageview', 'dp': 'home'}, 'expected': True}

print_result(display_ok=False)¶

Pretty print result of a test.

Two parts: prints the expected events that are missing by defaults or all expected events if display_ok=True then prints a summary.

Example

>>> from gaunit import TestCase
>>> r = gaunit.check_har("my_test_case", "tracking_plan.json", har=har)
>>> r.print_result(display_ok=True)
events in tracking plan: 3
================================================================================
{'t': 'pageview', 'dt': 'Home'}
                                                                        ... OK
================================================================================
{'t': 'pageview', 'dt': 'Product View'}
                                                                        ... OK
================================================================================
{'t': 'event',
'ec': 'ecommerce',
'ea': 'add_to_cart',
'ev': '44',
'pr1nm': 'Compton T-Shirt',
'pr1pr': '44.00'}
                                                                        ... OK
--------------------------------------------------------------------------------
GA events found: total:9 / ok:3 / missing:0
✔ OK: all expected events found

Parameters: display_ok (bool, optional) – if set to True, print all expected events, not only missing events. Defaults to False.

print_actual_events()¶

pretty print list of analytics hits from test case

says which analytics hit was in tracking plan (“OK” or “skip”), used in CLI

Exceptions¶

exception gaunit.GAUnitException(*args, **kwargs)¶: There was an exception while running GAUnit

exception gaunit.TrackingPlanError(*args, **kwargs)¶: Failed to instantiate TrackingPlan or TrackingPlan is invalid

exception gaunit.DictXORJsonPathError(*args, **kwargs)¶: One and only one argument must be provided: dict or JSON path

exception gaunit.TestCaseCheckError(*args, **kwargs)¶: Something is missing in Test Case to make a proper check