{"id":28042342,"url":"https://github.com/parallaxsecond/parsec-mock","last_synced_at":"2025-05-11T14:26:20.993Z","repository":{"id":45116467,"uuid":"349500341","full_name":"parallaxsecond/parsec-mock","owner":"parallaxsecond","description":"Mock Service for Parsec Client testing","archived":false,"fork":false,"pushed_at":"2022-01-07T07:33:14.000Z","size":113,"stargazers_count":3,"open_issues_count":1,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2023-03-03T14:32:52.945Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parallaxsecond.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-19T17:15:34.000Z","updated_at":"2022-01-07T07:33:18.000Z","dependencies_parsed_at":"2022-09-02T22:40:23.783Z","dependency_job_id":null,"html_url":"https://github.com/parallaxsecond/parsec-mock","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallaxsecond%2Fparsec-mock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallaxsecond%2Fparsec-mock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallaxsecond%2Fparsec-mock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallaxsecond%2Fparsec-mock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parallaxsecond","download_url":"https://codeload.github.com/parallaxsecond/parsec-mock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253578823,"owners_count":21930610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-11T14:26:20.358Z","updated_at":"2025-05-11T14:26:20.974Z","avatar_url":"https://github.com/parallaxsecond.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Parsec Mock\n\nThis repository contains a mock service to test Parsec clients and a test data generator to create\ntest data files for the mock service.\n\nSee [this issue](https://github.com/parallaxsecond/parsec/issues/350) which describes the proposal.\n\n# Prerequisites\n\nTo run the utilities in this repository, you will need python3 and pip installing.\n\nTo install package prerequisites, run the following from this folder:\n\n```\npip install -r requirements.txt\n```\n\n# Usage\n\n## Run the Mock Service\n\nCurrently the mock service only supports running test cases from a folder in a request matching\nmode. To run the service:\n\n```\n# To get help\npython parsec_mock/parsec_mock.py --help\n# To define test case folder (defaults to ./generator_output)\npython parsec_mock/parsec_mock.py --test-folder FOLDER_NAME\n# To define the unix socket address to listen to. Defaults to ./parsec.sock\npython parsec_mock/parsec_mock.py --parsec-socket SOCKET_ADDRESS\n```\n\nThe mock service loads all the test cases from the folder and, if it receives a request that matches\nthe (base64 encoded) `test_data.request` field in the test case file, it will repond with the base64\nencoded data in the `test_data.response` field.\n\nIf more than one test case shares the same `test_data.request` value, then the last one to be loaded\nwill be used.\n\n## Generate Test Data\n\nTo generate test data from test specs, run\n\n```\npython generator/generator.py\n```\n\nThis will parse the test specs in `generator/test_specs` and create test data in\n`generator_output/`.\n\n# Test Data\n\nThe `generator/generator.py` script creates test data files in the `generator_output` folder. These\ntest data files are intended for use, either with the mock service supplied here, or in other mock\nservices that may be developed for the parsec service or parsec clients. The test data files consist\nof the [test spec](#test-spec-format) (useful for the writer of a unit test), and test data, which\ncontains base64 encoded strings for a parsec request and a corresponding result.\n\nThe overall test data file format is, therefore:\n\n```\nspec:\n # for format see below\ntest_data:\n request: EKfAXh4AAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAA\n result: EKfAXh4AAQAAAAAAAAAAAAAAAAAAAAIAAAAAAAEAAAAAAAAACAE=\n```\n\n## Expected Use Of Test Data\n\nA client developer wants to test a parsec request in their client.\n\n- They select an appropriate test data file that fulfils the needs of their test (or [creates a new\n one](#writing-tests) in this repository and uses that)\n- They write client code that should generate a message to match the request section of the [test\n spec](#test-spec-format).\n- They start the mock service\n- They stimulate their client under test to send the request message to the mock service.\n- The mock service will check to see if the request message it received matches the expected value\n (this is an exact byte match).\n - If the match was successful, then it will return the configured match response\n - Otherwise, it will not return anything and close the connection\n- The client under test will attempt to decode the response. The results can be checked by the test\n code.\n\n## Writing Tests\n\nTo write a new test, a developer should create a test spec file in the `generator/test_specs`\nfolder, using the [format below](#test-spec-format).\n\nThey then need to write a generator function in `generator/generators`. This generator function\ntakes no arguments, and should output a tuple of python binary strings.\n\nThe first element of the tuple should be the protocol buffer encoded value of the request's\n*operation* message that is described in the `spec.request.body_description` field of the test spec.\nThe second element of the tuple should be the protocol buffer encoded *result* value of the response\nmessage that is described in the `spec.result.body_description` field of the test spec.\n\nThe generated protocol buffers python library files are in `generator/generators/protobuf`.\n\n## Test Spec Format\n\nTest specs are defined as YAML. An example file is shown below:\n\n```\n# Copyright 2021 Contributors to the Parsec project.\n# SPDX-License-Identifier: Apache-2.0\nspec:\n description: List opcodes using direct authentication\n request:\n header:\n magic_number: 0x5EC0A710\n header_size: 0x1E\n major_version_number: 0x01\n minor_version_number: 0x00\n flags: 0x0000\n provider: 0x00\n session_handle: 0x0000000000000000\n content_type: 0x00\n accept_type: 0x00\n auth_type: 0x00\n content_length: auto\n auth_length: auto\n opcode: 0x00000009\n status: 0x0000\n body_description: provider id 0x01\n auth: \n type: direct\n app_name: jimbob\n result:\n header:\n magic_number: 0x5EC0A710\n header_size: 0x1E\n major_version_number: 0x01\n minor_version_number: 0x00\n flags: 0x0000\n provider: 0x00\n session_handle: 0x0000000000000000\n content_type: 0x00\n accept_type: 0x00\n auth_type: 0x00\n content_length: auto\n auth_length: auto\n opcode: 0x00000009\n status: 0x0000\n body_description: list opcodes result [1,3,2]\n```\n\nThe whole test spec is defined in the spec: object in the file. In that spec, the fields are:\n\n| Field | Description |\n|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `description` | Description of test, not used in generation |\n| `request` | Settings for configuring the request data for the test data file |\n| `request.header` | Field values for the request header. Meanings of these files and valid values can be found in the [parsec book](https://parallaxsecond.github.io/parsec-book/parsec_client/wire_protocol.html). |\n| `request.header.content_length` | If this field has the value `auto` then its value is calculated from the generated request content. If the value is a number, then that value is used in the field instead. |\n| `request.header.auth_length` | If this field has the value `auto` then its value is calculated from the generated auth content. If the value is a number, then that value is used in the field instead. |\n| `request.body_description` | A free form description of the contents of the request content. Used for test writers (and generator writers) to understand how to construct the request object. This field is not used by the test generator. |\n| `request.auth.type` | This can either be `none`, which will cause the auth section of the message to be empty (equivalent of the No Authentication type of authentication); or it can be `direct`, which will cause the auth section of the message to contain authentication data corresponding to the format for Direct Authentication. If `direct` is set, then the `request.auth.app_name` field must be set. Note that this field does not cause the header `auth_type` field to be set. |\n| `request.auth.app_name` | Used to populate the auth section of the message when `direct` authentication is selected |\n| `response` | Settings for configuration the response data for the test data file |\n| `response.header` | Field values for the response header. Meanings of these files and valid values can be found in the [parsec book](https://parallaxsecond.github.io/parsec-book/parsec_client/wire_protocol.html). |\n| `response.header.content_length` | If this field has the value `auto` then its value is calculated from the generated response content. If the value is a number, then that value is used in the field instead |\n| `response.header.auth_length` | If this field has the value `auto` then its value is calculated from the generated auth content. If the value is a number, then that value is used in the field instead. |\n| `response.body_description` | A free form description of the contents of the response content. Used for test writers (and generator writers) to understand how to construct the result object. This field is not used by the test generator. |\n\n# Mock service testing\n\nThere is a very simple test for the mock service in the test folder. Run this from the current\nfolder:\n\n```\npython ./tests/mock_test.py\n```\n\nThis expects the mock service to be listening on `./parsec.sock` and to have the\n`generator_output/ping_no_auth.test.yaml` test spec loaded.\n\n# License\n\nThe software is provided under Apache-2.0. Contributions to this project are accepted under the same\nlicense.\n\n# Contributing\n\nPlease check the [**Contribution\nGuidelines**](https://parallaxsecond.github.io/parsec-book/contributing/index.html) to know more\nabout the contribution process.\n\n*Copyright 2021 Contributors to the Parsec project.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparallaxsecond%2Fparsec-mock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparallaxsecond%2Fparsec-mock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparallaxsecond%2Fparsec-mock/lists"}